zhongwei/gh-dieshen-claude-marketplace-plugins-development-skills

Fork 0

Files

Zhongwei Li 58598a4a49 Initial commit

2025-11-29 18:21:19 +08:00

12 KiB

Raw Permalink Blame History

API Documentation Generator Skill

Automatically generate comprehensive API documentation from code.

OpenAPI 3.0 Generation

From Express.js/TypeScript

/**
 * @openapi
 * /api/users:
 *   get:
 *     summary: List all users
 *     tags: [Users]
 *     parameters:
 *       - in: query
 *         name: page
 *         schema:
 *           type: integer
 *         description: Page number
 *       - in: query
 *         name: limit
 *         schema:
 *           type: integer
 *         description: Items per page
 *     responses:
 *       200:
 *         description: Success
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 users:
 *                   type: array
 *                   items:
 *                     $ref: '#/components/schemas/User'
 *                 pagination:
 *                   $ref: '#/components/schemas/Pagination'
 */
app.get('/api/users', async (req, res) => {
  // Implementation
});

Complete OpenAPI Spec Template

openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
  description: Comprehensive API for managing users and resources
  contact:
    name: API Support
    email: support@example.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://staging-api.example.com/v1
    description: Staging server
  - url: http://localhost:3000/v1
    description: Development server

tags:
  - name: Users
    description: User management endpoints
  - name: Authentication
    description: Authentication endpoints

paths:
  /auth/login:
    post:
      summary: User login
      tags: [Authentication]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                email:
                  type: string
                  format: email
                  example: user@example.com
                password:
                  type: string
                  format: password
                  example: SecurePass123!
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                  user:
                    $ref: '#/components/schemas/User'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /users:
    get:
      summary: List users
      tags: [Users]
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - in: query
          name: search
          schema:
            type: string
          description: Search term
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/Pagination'

    post:
      summary: Create user
      tags: [Users]
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserInput'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /users/{id}:
    parameters:
      - $ref: '#/components/parameters/UserIdParam'

    get:
      summary: Get user by ID
      tags: [Users]
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      summary: Update user
      tags: [Users]
      security:
        - BearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserInput'
      responses:
        '200':
          description: User updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

    delete:
      summary: Delete user
      tags: [Users]
      security:
        - BearerAuth: []
      responses:
        '204':
          description: User deleted
        '404':
          $ref: '#/components/responses/NotFound'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  parameters:
    UserIdParam:
      in: path
      name: id
      required: true
      schema:
        type: string
      description: User ID

    PageParam:
      in: query
      name: page
      schema:
        type: integer
        minimum: 1
        default: 1
      description: Page number

    LimitParam:
      in: query
      name: limit
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
      description: Items per page

  schemas:
    User:
      type: object
      required:
        - id
        - email
        - name
      properties:
        id:
          type: string
          example: usr_123abc
        email:
          type: string
          format: email
          example: user@example.com
        name:
          type: string
          example: John Doe
        role:
          type: string
          enum: [user, admin]
          default: user
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    CreateUserInput:
      type: object
      required:
        - email
        - name
        - password
      properties:
        email:
          type: string
          format: email
        name:
          type: string
          minLength: 1
          maxLength: 100
        password:
          type: string
          format: password
          minLength: 8

    UpdateUserInput:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
          format: email

    Pagination:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        totalPages:
          type: integer
        totalItems:
          type: integer
        hasNext:
          type: boolean
        hasPrevious:
          type: boolean

    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: object

  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

Generate from Code

TypeScript/Express

import swaggerJsdoc from 'swagger-jsdoc';
import swaggerUi from 'swagger-ui-express';

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'My API',
      version: '1.0.0',
    },
  },
  apis: ['./src/routes/*.ts'],
};

const specs = swaggerJsdoc(options);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));

Python/FastAPI (Auto-generated)

from fastapi import FastAPI, Query
from pydantic import BaseModel

app = FastAPI(
    title="My API",
    description="API documentation",
    version="1.0.0"
)

class User(BaseModel):
    id: str
    email: str
    name: str

@app.get("/users", response_model=list[User])
async def list_users(
    page: int = Query(1, ge=1, description="Page number"),
    limit: int = Query(20, ge=1, le=100, description="Items per page")
):
    """
    List all users with pagination.

    Returns a paginated list of users.
    """
    pass
# Docs auto-generated at /docs

README API Documentation

# API Documentation

## Base URL

https://api.example.com/v1


## Authentication
All endpoints require Bearer token authentication:

Authorization: Bearer YOUR_TOKEN_HERE


## Endpoints

### List Users
```http
GET /users?page=1&limit=20

Query Parameters:

page (integer, optional): Page number, default 1
limit (integer, optional): Items per page, default 20, max 100
search (string, optional): Search term

Response 200:

{
  "data": [
    {
      "id": "usr_123",
      "email": "user@example.com",
      "name": "John Doe",
      "role": "user",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "totalPages": 5,
    "totalItems": 95
  }
}

Create User

POST /users
Content-Type: application/json

{
  "email": "newuser@example.com",
  "name": "New User",
  "password": "SecurePass123!"
}

Response 201:

{
  "id": "usr_456",
  "email": "newuser@example.com",
  "name": "New User",
  "role": "user",
  "createdAt": "2024-01-01T00:00:00Z"
}

Error Responses

All errors follow this format:

{
  "code": "ERROR_CODE",
  "message": "Human-readable message",
  "details": {}
}

Status Codes

200 - Success
201 - Created
204 - No Content
400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
422 - Validation Error
429 - Rate Limit Exceeded
500 - Internal Server Error

Rate Limiting

100 requests per minute per IP
1000 requests per hour per user

Code Examples

JavaScript/Fetch

const response = await fetch('https://api.example.com/v1/users', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});
const data = await response.json();

Python/Requests

import requests

response = requests.get(
    'https://api.example.com/v1/users',
    headers={'Authorization': f'Bearer {token}'}
)
data = response.json()

cURL

curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.example.com/v1/users


## Postman Collection

Generate Postman collection from OpenAPI:
```bash
openapi2postmanv2 -s openapi.yaml -o postman_collection.json

Best Practices

Be Comprehensive: Document all endpoints, parameters, and responses
Provide Examples: Include real request/response examples
Document Errors: Show all possible error responses
Code Samples: Provide examples in multiple languages
Keep Updated: Auto-generate from code when possible
Version APIs: Include version in URL or headers
Security: Document authentication clearly
Rate Limits: Specify rate limiting rules
Changelog: Maintain API changelog
Interactive Docs: Use Swagger UI or similar

Tools

Swagger UI: Interactive API documentation
Redoc: Beautiful API documentation
Postman: API testing and documentation
Insomnia: API client and documentation
Stoplight: API design and documentation platform

12 KiB Raw Permalink Blame History