Initial commit
This commit is contained in:
Zhongwei Li
15
.claude-plugin/plugin.json
Normal file
15
.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,15 @@
|
|||||||
|
{
|
||||||
|
"name": "api-documentation-generator",
|
||||||
|
"description": "Generate comprehensive API documentation from OpenAPI/Swagger specs",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"author": {
|
||||||
|
"name": "Jeremy Longshore",
|
||||||
|
"email": "[email protected]"
|
||||||
|
},
|
||||||
|
"skills": [
|
||||||
|
"./skills"
|
||||||
|
],
|
||||||
|
"commands": [
|
||||||
|
"./commands"
|
||||||
|
]
|
||||||
|
}
|
||||||
3
README.md
Normal file
3
README.md
Normal file
@@ -0,0 +1,3 @@
|
|||||||
|
# api-documentation-generator
|
||||||
|
|
||||||
|
Generate comprehensive API documentation from OpenAPI/Swagger specs
|
||||||
1761
commands/generate-api-docs.md
Normal file
1761
commands/generate-api-docs.md
Normal file
File diff suppressed because it is too large
Load Diff
97
plugin.lock.json
Normal file
97
plugin.lock.json
Normal file
@@ -0,0 +1,97 @@
|
|||||||
|
{
|
||||||
|
"$schema": "internal://schemas/plugin.lock.v1.json",
|
||||||
|
"pluginId": "gh:jeremylongshore/claude-code-plugins-plus:plugins/api-development/api-documentation-generator",
|
||||||
|
"normalized": {
|
||||||
|
"repo": null,
|
||||||
|
"ref": "refs/tags/v20251128.0",
|
||||||
|
"commit": "1a700773429ce9eb2d2b4a7cddc6fd5ac219964e",
|
||||||
|
"treeHash": "d12704c044be40b210314bd5199871c5fdac232a3df42ff328f525f5bd69b45d",
|
||||||
|
"generatedAt": "2025-11-28T10:18:05.806396Z",
|
||||||
|
"toolVersion": "publish_plugins.py@0.2.0"
|
||||||
|
},
|
||||||
|
"origin": {
|
||||||
|
"remote": "git@github.com:zhongweili/42plugin-data.git",
|
||||||
|
"branch": "master",
|
||||||
|
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
|
||||||
|
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
|
||||||
|
},
|
||||||
|
"manifest": {
|
||||||
|
"name": "api-documentation-generator",
|
||||||
|
"description": "Generate comprehensive API documentation from OpenAPI/Swagger specs",
|
||||||
|
"version": "1.0.0"
|
||||||
|
},
|
||||||
|
"content": {
|
||||||
|
"files": [
|
||||||
|
{
|
||||||
|
"path": "README.md",
|
||||||
|
"sha256": "64c503e7c37528b33387993426872f2a20db94c4d2ed8947d9f4b44535d26e19"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": ".claude-plugin/plugin.json",
|
||||||
|
"sha256": "d4abe111c1d6d14d440698a06f9091907f0b1388444eaee80a88c3d4e456d89d"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "commands/generate-api-docs.md",
|
||||||
|
"sha256": "492bca036d5983a8eb2f917de0bcb30e2bb933139296674cb39cae13288e14a6"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/skill-adapter/references/examples.md",
|
||||||
|
"sha256": "922bbc3c4ebf38b76f515b5c1998ebde6bf902233e00e2c5a0e9176f975a7572"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/skill-adapter/references/best-practices.md",
|
||||||
|
"sha256": "c8f32b3566252f50daacd346d7045a1060c718ef5cfb07c55a0f2dec5f1fb39e"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/skill-adapter/references/README.md",
|
||||||
|
"sha256": "af4382b4481f73300e397a3279606584873856f5b10d9d83bd38d9e188c47aa5"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/skill-adapter/scripts/helper-template.sh",
|
||||||
|
"sha256": "0881d5660a8a7045550d09ae0acc15642c24b70de6f08808120f47f86ccdf077"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/skill-adapter/scripts/validation.sh",
|
||||||
|
"sha256": "92551a29a7f512d2036e4f1fb46c2a3dc6bff0f7dde4a9f699533e446db48502"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/skill-adapter/scripts/README.md",
|
||||||
|
"sha256": "1ec1ddec244a288434f4c2d756829856e462f8a1772422f170ae092749412c7c"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/skill-adapter/assets/test-data.json",
|
||||||
|
"sha256": "ac17dca3d6e253a5f39f2a2f1b388e5146043756b05d9ce7ac53a0042eee139d"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/skill-adapter/assets/example_api_definition.yaml",
|
||||||
|
"sha256": "22fc9e5a8f1dc80d0928f086c208cc9414c1bd9eb2b108f030ccd0c66fc83141"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/skill-adapter/assets/README.md",
|
||||||
|
"sha256": "e0d2288e042e2a1ffa89f86f1885017f331fbcd875879f483a0525118910a75a"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/skill-adapter/assets/openapi_template.yaml",
|
||||||
|
"sha256": "93862d98ae602e06a697de5c0387b946028ab2e1b177935131657d8844c09ce2"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/skill-adapter/assets/skill-schema.json",
|
||||||
|
"sha256": "f5639ba823a24c9ac4fb21444c0717b7aefde1a4993682897f5bf544f863c2cd"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/skill-adapter/assets/swagger_ui_config.json",
|
||||||
|
"sha256": "cddfbc36e35e455ef988c4e79bc226f24761d70f69cee0fcf4c1a756d906467a"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/skill-adapter/assets/config-template.json",
|
||||||
|
"sha256": "0c2ba33d2d3c5ccb266c0848fc43caa68a2aa6a80ff315d4b378352711f83e1c"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"dirSha256": "d12704c044be40b210314bd5199871c5fdac232a3df42ff328f525f5bd69b45d"
|
||||||
|
},
|
||||||
|
"security": {
|
||||||
|
"scannedAt": null,
|
||||||
|
"scannerVersion": null,
|
||||||
|
"flags": []
|
||||||
|
}
|
||||||
|
}
|
||||||
7
skills/skill-adapter/assets/README.md
Normal file
7
skills/skill-adapter/assets/README.md
Normal file
@@ -0,0 +1,7 @@
|
|||||||
|
# Assets
|
||||||
|
|
||||||
|
Bundled resources for api-documentation-generator skill
|
||||||
|
|
||||||
|
- [ ] openapi_template.yaml: A template for creating OpenAPI documentation.
|
||||||
|
- [ ] swagger_ui_config.json: A configuration file for customizing the Swagger UI.
|
||||||
|
- [ ] example_api_definition.yaml: Example of a complete API definition in OpenAPI format.
|
||||||
32
skills/skill-adapter/assets/config-template.json
Normal file
32
skills/skill-adapter/assets/config-template.json
Normal file
@@ -0,0 +1,32 @@
|
|||||||
|
{
|
||||||
|
"skill": {
|
||||||
|
"name": "skill-name",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"enabled": true,
|
||||||
|
"settings": {
|
||||||
|
"verbose": false,
|
||||||
|
"autoActivate": true,
|
||||||
|
"toolRestrictions": true
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"triggers": {
|
||||||
|
"keywords": [
|
||||||
|
"example-trigger-1",
|
||||||
|
"example-trigger-2"
|
||||||
|
],
|
||||||
|
"patterns": []
|
||||||
|
},
|
||||||
|
"tools": {
|
||||||
|
"allowed": [
|
||||||
|
"Read",
|
||||||
|
"Grep",
|
||||||
|
"Bash"
|
||||||
|
],
|
||||||
|
"restricted": []
|
||||||
|
},
|
||||||
|
"metadata": {
|
||||||
|
"author": "Plugin Author",
|
||||||
|
"category": "general",
|
||||||
|
"tags": []
|
||||||
|
}
|
||||||
|
}
|
||||||
236
skills/skill-adapter/assets/example_api_definition.yaml
Normal file
236
skills/skill-adapter/assets/example_api_definition.yaml
Normal file
@@ -0,0 +1,236 @@
|
|||||||
|
# OpenAPI 3.0.3 specification for example API
|
||||||
|
openapi: 3.0.3
|
||||||
|
|
||||||
|
# API information
|
||||||
|
info:
|
||||||
|
title: Example API
|
||||||
|
version: 1.0.0
|
||||||
|
description: This is a sample API definition for demonstration purposes.
|
||||||
|
termsOfService: https://www.example.com/terms/
|
||||||
|
contact:
|
||||||
|
name: API Support
|
||||||
|
url: https://www.example.com/support
|
||||||
|
email: support@example.com
|
||||||
|
license:
|
||||||
|
name: MIT
|
||||||
|
url: https://opensource.org/licenses/MIT
|
||||||
|
|
||||||
|
# Server URLs
|
||||||
|
servers:
|
||||||
|
- url: https://api.example.com/v1
|
||||||
|
description: Production server
|
||||||
|
- url: https://staging.api.example.com/v1
|
||||||
|
description: Staging server
|
||||||
|
|
||||||
|
# Paths (API endpoints)
|
||||||
|
paths:
|
||||||
|
/users:
|
||||||
|
get:
|
||||||
|
summary: Get all users
|
||||||
|
description: Returns a list of all users.
|
||||||
|
operationId: getUsers
|
||||||
|
tags:
|
||||||
|
- Users
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Successful operation
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/User'
|
||||||
|
'500':
|
||||||
|
description: Internal server error
|
||||||
|
post:
|
||||||
|
summary: Create a new user
|
||||||
|
description: Creates a new user with the provided information.
|
||||||
|
operationId: createUser
|
||||||
|
tags:
|
||||||
|
- Users
|
||||||
|
requestBody:
|
||||||
|
description: User object to be created
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/UserCreate'
|
||||||
|
responses:
|
||||||
|
'201':
|
||||||
|
description: User created successfully
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/User'
|
||||||
|
'400':
|
||||||
|
description: Invalid input
|
||||||
|
'500':
|
||||||
|
description: Internal server error
|
||||||
|
|
||||||
|
/users/{userId}:
|
||||||
|
get:
|
||||||
|
summary: Get a user by ID
|
||||||
|
description: Returns a single user based on the provided ID.
|
||||||
|
operationId: getUserById
|
||||||
|
tags:
|
||||||
|
- Users
|
||||||
|
parameters:
|
||||||
|
- name: userId
|
||||||
|
in: path
|
||||||
|
description: ID of the user to retrieve
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
format: int64
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Successful operation
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/User'
|
||||||
|
'404':
|
||||||
|
description: User not found
|
||||||
|
'500':
|
||||||
|
description: Internal server error
|
||||||
|
put:
|
||||||
|
summary: Update a user by ID
|
||||||
|
description: Updates an existing user with the provided information.
|
||||||
|
operationId: updateUser
|
||||||
|
tags:
|
||||||
|
- Users
|
||||||
|
parameters:
|
||||||
|
- name: userId
|
||||||
|
in: path
|
||||||
|
description: ID of the user to update
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
format: int64
|
||||||
|
requestBody:
|
||||||
|
description: User object to be updated
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/UserUpdate'
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: User updated successfully
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/User'
|
||||||
|
'400':
|
||||||
|
description: Invalid input
|
||||||
|
'404':
|
||||||
|
description: User not found
|
||||||
|
'500':
|
||||||
|
description: Internal server error
|
||||||
|
delete:
|
||||||
|
summary: Delete a user by ID
|
||||||
|
description: Deletes a user based on the provided ID.
|
||||||
|
operationId: deleteUser
|
||||||
|
tags:
|
||||||
|
- Users
|
||||||
|
parameters:
|
||||||
|
- name: userId
|
||||||
|
in: path
|
||||||
|
description: ID of the user to delete
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
format: int64
|
||||||
|
responses:
|
||||||
|
'204':
|
||||||
|
description: User deleted successfully (no content)
|
||||||
|
'404':
|
||||||
|
description: User not found
|
||||||
|
'500':
|
||||||
|
description: Internal server error
|
||||||
|
|
||||||
|
# Components (reusable schemas, parameters, etc.)
|
||||||
|
components:
|
||||||
|
schemas:
|
||||||
|
User:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
id:
|
||||||
|
type: integer
|
||||||
|
format: int64
|
||||||
|
description: Unique identifier for the user
|
||||||
|
username:
|
||||||
|
type: string
|
||||||
|
description: User's username
|
||||||
|
email:
|
||||||
|
type: string
|
||||||
|
format: email
|
||||||
|
description: User's email address
|
||||||
|
firstName:
|
||||||
|
type: string
|
||||||
|
description: User's first name
|
||||||
|
lastName:
|
||||||
|
type: string
|
||||||
|
description: User's last name
|
||||||
|
createdAt:
|
||||||
|
type: string
|
||||||
|
format: date-time
|
||||||
|
description: Date and time the user was created
|
||||||
|
required:
|
||||||
|
- id
|
||||||
|
- username
|
||||||
|
- email
|
||||||
|
UserCreate:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
username:
|
||||||
|
type: string
|
||||||
|
description: User's username
|
||||||
|
email:
|
||||||
|
type: string
|
||||||
|
format: email
|
||||||
|
description: User's email address
|
||||||
|
firstName:
|
||||||
|
type: string
|
||||||
|
description: User's first name
|
||||||
|
lastName:
|
||||||
|
type: string
|
||||||
|
description: User's last name
|
||||||
|
password:
|
||||||
|
type: string
|
||||||
|
description: User's password (REPLACE_ME - consider security best practices)
|
||||||
|
required:
|
||||||
|
- username
|
||||||
|
- email
|
||||||
|
- password
|
||||||
|
UserUpdate:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
username:
|
||||||
|
type: string
|
||||||
|
description: User's username
|
||||||
|
email:
|
||||||
|
type: string
|
||||||
|
format: email
|
||||||
|
description: User's email address
|
||||||
|
firstName:
|
||||||
|
type: string
|
||||||
|
description: User's first name
|
||||||
|
lastName:
|
||||||
|
type: string
|
||||||
|
description: User's last name
|
||||||
|
|
||||||
|
securitySchemes:
|
||||||
|
bearerAuth: # Define a security scheme for JWT authentication
|
||||||
|
type: http
|
||||||
|
scheme: bearer
|
||||||
|
bearerFormat: JWT
|
||||||
|
|
||||||
|
# Security requirements for the API
|
||||||
|
security:
|
||||||
|
- bearerAuth: [] # Apply the JWT authentication scheme globally
|
||||||
|
|
||||||
|
# Tags (for grouping operations)
|
||||||
|
tags:
|
||||||
|
- name: Users
|
||||||
|
description: Operations related to users
|
||||||
137
skills/skill-adapter/assets/openapi_template.yaml
Normal file
137
skills/skill-adapter/assets/openapi_template.yaml
Normal file
@@ -0,0 +1,137 @@
|
|||||||
|
# openapi_template.yaml
|
||||||
|
# This is a template for creating OpenAPI 3.0.3 documentation.
|
||||||
|
|
||||||
|
openapi: 3.0.3
|
||||||
|
info:
|
||||||
|
title: REPLACE_ME - API Documentation
|
||||||
|
version: 1.0.0
|
||||||
|
description: YOUR_VALUE_HERE - Description of the API.
|
||||||
|
termsOfService: https://example.com/terms/
|
||||||
|
contact:
|
||||||
|
name: API Support
|
||||||
|
url: https://example.com/support
|
||||||
|
email: support@example.com
|
||||||
|
license:
|
||||||
|
name: MIT
|
||||||
|
url: https://opensource.org/licenses/MIT
|
||||||
|
|
||||||
|
# Define the servers where the API is hosted.
|
||||||
|
servers:
|
||||||
|
- url: https://YOUR_VALUE_HERE/api/v1
|
||||||
|
description: Production server
|
||||||
|
- url: http://localhost:8080/api/v1
|
||||||
|
description: Development server
|
||||||
|
|
||||||
|
# Define security schemes (e.g., API key, OAuth2).
|
||||||
|
components:
|
||||||
|
securitySchemes:
|
||||||
|
ApiKeyAuth: # Security scheme name
|
||||||
|
type: apiKey
|
||||||
|
in: header # Can be "header", "query" or "cookie"
|
||||||
|
name: X-API-Key # The name of the header/query parameter/cookie
|
||||||
|
|
||||||
|
# Define paths and operations.
|
||||||
|
paths:
|
||||||
|
/items:
|
||||||
|
get:
|
||||||
|
summary: Get a list of items
|
||||||
|
description: Returns a list of all available items.
|
||||||
|
security:
|
||||||
|
- ApiKeyAuth: [] # Apply the ApiKeyAuth security scheme
|
||||||
|
tags:
|
||||||
|
- Items
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Successful operation
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/Item'
|
||||||
|
'500':
|
||||||
|
description: Internal server error
|
||||||
|
|
||||||
|
post:
|
||||||
|
summary: Create a new item
|
||||||
|
description: Creates a new item with the given data.
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ItemInput'
|
||||||
|
responses:
|
||||||
|
'201':
|
||||||
|
description: Item created successfully
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/Item'
|
||||||
|
'400':
|
||||||
|
description: Bad request
|
||||||
|
|
||||||
|
/items/{itemId}:
|
||||||
|
get:
|
||||||
|
summary: Get an item by ID
|
||||||
|
description: Returns a single item based on its ID.
|
||||||
|
parameters:
|
||||||
|
- in: path
|
||||||
|
name: itemId
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
description: The ID of the item to retrieve.
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Successful operation
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/Item'
|
||||||
|
'404':
|
||||||
|
description: Item not found
|
||||||
|
|
||||||
|
# Define reusable schemas.
|
||||||
|
components:
|
||||||
|
schemas:
|
||||||
|
Item:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
id:
|
||||||
|
type: integer
|
||||||
|
description: The unique identifier for the item.
|
||||||
|
name:
|
||||||
|
type: string
|
||||||
|
description: The name of the item.
|
||||||
|
description:
|
||||||
|
type: string
|
||||||
|
description: A description of the item.
|
||||||
|
price:
|
||||||
|
type: number
|
||||||
|
format: float
|
||||||
|
description: The price of the item.
|
||||||
|
required:
|
||||||
|
- id
|
||||||
|
- name
|
||||||
|
ItemInput:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
name:
|
||||||
|
type: string
|
||||||
|
description: The name of the item.
|
||||||
|
description:
|
||||||
|
type: string
|
||||||
|
description: A description of the item.
|
||||||
|
price:
|
||||||
|
type: number
|
||||||
|
format: float
|
||||||
|
description: The price of the item.
|
||||||
|
required:
|
||||||
|
- name
|
||||||
|
- price
|
||||||
|
|
||||||
|
# Define tags for grouping operations.
|
||||||
|
tags:
|
||||||
|
- name: Items
|
||||||
|
description: Operations related to items.
|
||||||
28
skills/skill-adapter/assets/skill-schema.json
Normal file
28
skills/skill-adapter/assets/skill-schema.json
Normal file
@@ -0,0 +1,28 @@
|
|||||||
|
{
|
||||||
|
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||||
|
"title": "Claude Skill Configuration",
|
||||||
|
"type": "object",
|
||||||
|
"required": ["name", "description"],
|
||||||
|
"properties": {
|
||||||
|
"name": {
|
||||||
|
"type": "string",
|
||||||
|
"pattern": "^[a-z0-9-]+$",
|
||||||
|
"maxLength": 64,
|
||||||
|
"description": "Skill identifier (lowercase, hyphens only)"
|
||||||
|
},
|
||||||
|
"description": {
|
||||||
|
"type": "string",
|
||||||
|
"maxLength": 1024,
|
||||||
|
"description": "What the skill does and when to use it"
|
||||||
|
},
|
||||||
|
"allowed-tools": {
|
||||||
|
"type": "string",
|
||||||
|
"description": "Comma-separated list of allowed tools"
|
||||||
|
},
|
||||||
|
"version": {
|
||||||
|
"type": "string",
|
||||||
|
"pattern": "^\\d+\\.\\d+\\.\\d+$",
|
||||||
|
"description": "Semantic version (x.y.z)"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
51
skills/skill-adapter/assets/swagger_ui_config.json
Normal file
51
skills/skill-adapter/assets/swagger_ui_config.json
Normal file
@@ -0,0 +1,51 @@
|
|||||||
|
{
|
||||||
|
"_comment": "Swagger UI configuration file",
|
||||||
|
"swagger": {
|
||||||
|
"_comment": "Swagger UI configuration options",
|
||||||
|
"url": "/openapi.json",
|
||||||
|
"dom_id": "#swagger-ui",
|
||||||
|
"deepLinking": true,
|
||||||
|
"presets": [
|
||||||
|
"SwaggerUIBundle.presets.apis",
|
||||||
|
"SwaggerUIStandalonePreset"
|
||||||
|
],
|
||||||
|
"plugins": [
|
||||||
|
"SwaggerUIBundle.plugins.DownloadUrl"
|
||||||
|
],
|
||||||
|
"layout": "StandaloneLayout",
|
||||||
|
"docExpansion": "none",
|
||||||
|
"filter": true,
|
||||||
|
"showRequestDuration": true,
|
||||||
|
"requestInterceptor": "(req) => { console.log('Request Interceptor:', req); return req; }",
|
||||||
|
"responseInterceptor": "(res) => { console.log('Response Interceptor:', res); return res; }",
|
||||||
|
"displayOperationId": false,
|
||||||
|
"displayRequestDuration": true,
|
||||||
|
"defaultModelsExpandDepth": 1,
|
||||||
|
"defaultModelExpandDepth": 1,
|
||||||
|
"defaultModelRendering": "example",
|
||||||
|
"displayRequestDuration": true,
|
||||||
|
"showExtensions": true,
|
||||||
|
"showCommonExtensions": true,
|
||||||
|
"validatorUrl": null,
|
||||||
|
"oauth2RedirectUrl": null,
|
||||||
|
"syntaxHighlight": {
|
||||||
|
"activate": true,
|
||||||
|
"theme": "monokai"
|
||||||
|
},
|
||||||
|
"tryItOutEnabled": true,
|
||||||
|
"persistAuthorization": true
|
||||||
|
},
|
||||||
|
"customCss": ".swagger-ui .topbar { display: none; }",
|
||||||
|
"customJs": null,
|
||||||
|
"customFavIcon": null,
|
||||||
|
"customSiteTitle": "API Documentation",
|
||||||
|
"oauth2": {
|
||||||
|
"_comment": "OAuth 2.0 configuration (optional)",
|
||||||
|
"clientId": "your-client-id",
|
||||||
|
"clientSecret": "your-client-secret",
|
||||||
|
"realm": "your-realm",
|
||||||
|
"appName": "API Documentation App",
|
||||||
|
"scopeSeparator": " ",
|
||||||
|
"additionalQueryStringParams": {}
|
||||||
|
}
|
||||||
|
}
|
||||||
27
skills/skill-adapter/assets/test-data.json
Normal file
27
skills/skill-adapter/assets/test-data.json
Normal file
@@ -0,0 +1,27 @@
|
|||||||
|
{
|
||||||
|
"testCases": [
|
||||||
|
{
|
||||||
|
"name": "Basic activation test",
|
||||||
|
"input": "trigger phrase example",
|
||||||
|
"expected": {
|
||||||
|
"activated": true,
|
||||||
|
"toolsUsed": ["Read", "Grep"],
|
||||||
|
"success": true
|
||||||
|
}
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "Complex workflow test",
|
||||||
|
"input": "multi-step trigger example",
|
||||||
|
"expected": {
|
||||||
|
"activated": true,
|
||||||
|
"steps": 3,
|
||||||
|
"toolsUsed": ["Read", "Write", "Bash"],
|
||||||
|
"success": true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"fixtures": {
|
||||||
|
"sampleInput": "example data",
|
||||||
|
"expectedOutput": "processed result"
|
||||||
|
}
|
||||||
|
}
|
||||||
7
skills/skill-adapter/references/README.md
Normal file
7
skills/skill-adapter/references/README.md
Normal file
@@ -0,0 +1,7 @@
|
|||||||
|
# References
|
||||||
|
|
||||||
|
Bundled resources for api-documentation-generator skill
|
||||||
|
|
||||||
|
- [ ] openapi_specification.md: A detailed explanation of the OpenAPI specification and best practices.
|
||||||
|
- [ ] swagger_ui_integration.md: Documentation on how to integrate Swagger UI with the generated OpenAPI documentation.
|
||||||
|
- [ ] api_documentation_best_practices.md: A guide to writing effective and comprehensive API documentation.
|
||||||
69
skills/skill-adapter/references/best-practices.md
Normal file
69
skills/skill-adapter/references/best-practices.md
Normal file
@@ -0,0 +1,69 @@
|
|||||||
|
# Skill Best Practices
|
||||||
|
|
||||||
|
Guidelines for optimal skill usage and development.
|
||||||
|
|
||||||
|
## For Users
|
||||||
|
|
||||||
|
### Activation Best Practices
|
||||||
|
|
||||||
|
1. **Use Clear Trigger Phrases**
|
||||||
|
- Match phrases from skill description
|
||||||
|
- Be specific about intent
|
||||||
|
- Provide necessary context
|
||||||
|
|
||||||
|
2. **Provide Sufficient Context**
|
||||||
|
- Include relevant file paths
|
||||||
|
- Specify scope of analysis
|
||||||
|
- Mention any constraints
|
||||||
|
|
||||||
|
3. **Understand Tool Permissions**
|
||||||
|
- Check allowed-tools in frontmatter
|
||||||
|
- Know what the skill can/cannot do
|
||||||
|
- Request appropriate actions
|
||||||
|
|
||||||
|
### Workflow Optimization
|
||||||
|
|
||||||
|
- Start with simple requests
|
||||||
|
- Build up to complex workflows
|
||||||
|
- Verify each step before proceeding
|
||||||
|
- Use skill consistently for related tasks
|
||||||
|
|
||||||
|
## For Developers
|
||||||
|
|
||||||
|
### Skill Development Guidelines
|
||||||
|
|
||||||
|
1. **Clear Descriptions**
|
||||||
|
- Include explicit trigger phrases
|
||||||
|
- Document all capabilities
|
||||||
|
- Specify limitations
|
||||||
|
|
||||||
|
2. **Proper Tool Permissions**
|
||||||
|
- Use minimal necessary tools
|
||||||
|
- Document security implications
|
||||||
|
- Test with restricted tools
|
||||||
|
|
||||||
|
3. **Comprehensive Documentation**
|
||||||
|
- Provide usage examples
|
||||||
|
- Document common pitfalls
|
||||||
|
- Include troubleshooting guide
|
||||||
|
|
||||||
|
### Maintenance
|
||||||
|
|
||||||
|
- Keep version updated
|
||||||
|
- Test after tool updates
|
||||||
|
- Monitor user feedback
|
||||||
|
- Iterate on descriptions
|
||||||
|
|
||||||
|
## Performance Tips
|
||||||
|
|
||||||
|
- Scope skills to specific domains
|
||||||
|
- Avoid overlapping trigger phrases
|
||||||
|
- Keep descriptions under 1024 chars
|
||||||
|
- Test activation reliability
|
||||||
|
|
||||||
|
## Security Considerations
|
||||||
|
|
||||||
|
- Never include secrets in skill files
|
||||||
|
- Validate all inputs
|
||||||
|
- Use read-only tools when possible
|
||||||
|
- Document security requirements
|
||||||
70
skills/skill-adapter/references/examples.md
Normal file
70
skills/skill-adapter/references/examples.md
Normal file
@@ -0,0 +1,70 @@
|
|||||||
|
# Skill Usage Examples
|
||||||
|
|
||||||
|
This document provides practical examples of how to use this skill effectively.
|
||||||
|
|
||||||
|
## Basic Usage
|
||||||
|
|
||||||
|
### Example 1: Simple Activation
|
||||||
|
|
||||||
|
**User Request:**
|
||||||
|
```
|
||||||
|
[Describe trigger phrase here]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Skill Response:**
|
||||||
|
1. Analyzes the request
|
||||||
|
2. Performs the required action
|
||||||
|
3. Returns results
|
||||||
|
|
||||||
|
### Example 2: Complex Workflow
|
||||||
|
|
||||||
|
**User Request:**
|
||||||
|
```
|
||||||
|
[Describe complex scenario]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Workflow:**
|
||||||
|
1. Step 1: Initial analysis
|
||||||
|
2. Step 2: Data processing
|
||||||
|
3. Step 3: Result generation
|
||||||
|
4. Step 4: Validation
|
||||||
|
|
||||||
|
## Advanced Patterns
|
||||||
|
|
||||||
|
### Pattern 1: Chaining Operations
|
||||||
|
|
||||||
|
Combine this skill with other tools:
|
||||||
|
```
|
||||||
|
Step 1: Use this skill for [purpose]
|
||||||
|
Step 2: Chain with [other tool]
|
||||||
|
Step 3: Finalize with [action]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Pattern 2: Error Handling
|
||||||
|
|
||||||
|
If issues occur:
|
||||||
|
- Check trigger phrase matches
|
||||||
|
- Verify context is available
|
||||||
|
- Review allowed-tools permissions
|
||||||
|
|
||||||
|
## Tips & Best Practices
|
||||||
|
|
||||||
|
- ✅ Be specific with trigger phrases
|
||||||
|
- ✅ Provide necessary context
|
||||||
|
- ✅ Check tool permissions match needs
|
||||||
|
- ❌ Avoid vague requests
|
||||||
|
- ❌ Don't mix unrelated tasks
|
||||||
|
|
||||||
|
## Common Issues
|
||||||
|
|
||||||
|
**Issue:** Skill doesn't activate
|
||||||
|
**Solution:** Use exact trigger phrases from description
|
||||||
|
|
||||||
|
**Issue:** Unexpected results
|
||||||
|
**Solution:** Check input format and context
|
||||||
|
|
||||||
|
## See Also
|
||||||
|
|
||||||
|
- Main SKILL.md for full documentation
|
||||||
|
- scripts/ for automation helpers
|
||||||
|
- assets/ for configuration examples
|
||||||
7
skills/skill-adapter/scripts/README.md
Normal file
7
skills/skill-adapter/scripts/README.md
Normal file
@@ -0,0 +1,7 @@
|
|||||||
|
# Scripts
|
||||||
|
|
||||||
|
Bundled resources for api-documentation-generator skill
|
||||||
|
|
||||||
|
- [ ] generate_openapi.py: Script to automatically generate OpenAPI documentation from code comments or existing API endpoints.
|
||||||
|
- [ ] validate_openapi.py: Script to validate the generated OpenAPI documentation against the OpenAPI specification.
|
||||||
|
- [ ] convert_openapi.py: Script to convert OpenAPI documentation between different formats (e.g., YAML to JSON).
|
||||||
42
skills/skill-adapter/scripts/helper-template.sh
Executable file
42
skills/skill-adapter/scripts/helper-template.sh
Executable file
@@ -0,0 +1,42 @@
|
|||||||
|
#!/bin/bash
|
||||||
|
# Helper script template for skill automation
|
||||||
|
# Customize this for your skill's specific needs
|
||||||
|
|
||||||
|
set -e
|
||||||
|
|
||||||
|
function show_usage() {
|
||||||
|
echo "Usage: $0 [options]"
|
||||||
|
echo ""
|
||||||
|
echo "Options:"
|
||||||
|
echo " -h, --help Show this help message"
|
||||||
|
echo " -v, --verbose Enable verbose output"
|
||||||
|
echo ""
|
||||||
|
}
|
||||||
|
|
||||||
|
# Parse arguments
|
||||||
|
VERBOSE=false
|
||||||
|
|
||||||
|
while [[ $# -gt 0 ]]; do
|
||||||
|
case $1 in
|
||||||
|
-h|--help)
|
||||||
|
show_usage
|
||||||
|
exit 0
|
||||||
|
;;
|
||||||
|
-v|--verbose)
|
||||||
|
VERBOSE=true
|
||||||
|
shift
|
||||||
|
;;
|
||||||
|
*)
|
||||||
|
echo "Unknown option: $1"
|
||||||
|
show_usage
|
||||||
|
exit 1
|
||||||
|
;;
|
||||||
|
esac
|
||||||
|
done
|
||||||
|
|
||||||
|
# Your skill logic here
|
||||||
|
if [ "$VERBOSE" = true ]; then
|
||||||
|
echo "Running skill automation..."
|
||||||
|
fi
|
||||||
|
|
||||||
|
echo "✅ Complete"
|
||||||
32
skills/skill-adapter/scripts/validation.sh
Executable file
32
skills/skill-adapter/scripts/validation.sh
Executable file
@@ -0,0 +1,32 @@
|
|||||||
|
#!/bin/bash
|
||||||
|
# Skill validation helper
|
||||||
|
# Validates skill activation and functionality
|
||||||
|
|
||||||
|
set -e
|
||||||
|
|
||||||
|
echo "🔍 Validating skill..."
|
||||||
|
|
||||||
|
# Check if SKILL.md exists
|
||||||
|
if [ ! -f "../SKILL.md" ]; then
|
||||||
|
echo "❌ Error: SKILL.md not found"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Validate frontmatter
|
||||||
|
if ! grep -q "^---$" "../SKILL.md"; then
|
||||||
|
echo "❌ Error: No frontmatter found"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Check required fields
|
||||||
|
if ! grep -q "^name:" "../SKILL.md"; then
|
||||||
|
echo "❌ Error: Missing 'name' field"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
if ! grep -q "^description:" "../SKILL.md"; then
|
||||||
|
echo "❌ Error: Missing 'description' field"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
echo "✅ Skill validation passed"
|
||||||
Reference in New Issue
Block a user