Initial commit

.claude-plugin/plugin.json

@@ -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"
+  ]
+}

README.md

@@ -0,0 +1,3 @@
+# api-documentation-generator
+
+Generate comprehensive API documentation from OpenAPI/Swagger specs

plugin.lock.json

@@ -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": []
+  }
+}

skills/skill-adapter/assets/README.md

@@ -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.

skills/skill-adapter/assets/config-template.json

@@ -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": []
+  }
+}

skills/skill-adapter/assets/example_api_definition.yaml

@@ -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

skills/skill-adapter/assets/openapi_template.yaml

@@ -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.

skills/skill-adapter/assets/skill-schema.json

@@ -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)"
+    }
+  }
+}

skills/skill-adapter/assets/swagger_ui_config.json

@@ -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": {}
+  }
+}

skills/skill-adapter/assets/test-data.json

@@ -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"
+  }
+}

skills/skill-adapter/references/README.md

@@ -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.

skills/skill-adapter/references/best-practices.md

@@ -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

skills/skill-adapter/references/examples.md

@@ -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

skills/skill-adapter/scripts/README.md

@@ -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).

skills/skill-adapter/scripts/helper-template.sh

@@ -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"

skills/skill-adapter/scripts/validation.sh

@@ -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"