api-docs-generator

Original：🇺🇸 English
Translated

Generates API documentation from code including OpenAPI specs, JSDoc, and Python docstrings. Use when documenting APIs, REST endpoints, or library functions.

17installs
Sourcearmanzeroeight/fastagent-plugins
Added on

NPX Install

npx skill4agent add armanzeroeight/fastagent-plugins api-docs-generator

Tags

Translated version includes tags in frontmatter
api-documentationopenapi-specjsdocpython-docstringsswagger-tools

SKILL.md Content

View Translation Comparison →

API Documentation Generator

Quick Start

Generate API docs based on code type:
bash
# OpenAPI from Express routes
npx swagger-jsdoc -d swaggerDef.js routes/*.js

# JSDoc for JavaScript
npx jsdoc src/ -d docs/

# Python docstrings
pdoc --html --output-dir docs/ mypackage/

Instructions

Step 1: Identify API Type

Determine documentation approach:
API TypeToolOutput
REST APIOpenAPI/SwaggerInteractive API docs
GraphQLGraphQL SchemaSchema documentation
JavaScript LibraryJSDocHTML reference
Python LibrarySphinx/pdocHTML reference

Step 2: Extract Documentation

REST API (OpenAPI):
Scan route files for JSDoc comments:
javascript
/**
 * @swagger
 * /users:
 *   get:
 *     summary: Get all users
 *     responses:
 *       200:
 *         description: List of users
 */
router.get('/users', getUsers);
Generate spec:
bash
npx swagger-jsdoc -d swaggerDef.js routes/*.js -o openapi.json
JavaScript Library (JSDoc):
javascript
/**
 * Adds two numbers together.
 * @param {number} a - First number
 * @param {number} b - Second number
 * @returns {number} Sum of a and b
 * @example
 * add(2, 3); // returns 5
 */
function add(a, b) {
  return a + b;
}
Python (Docstrings):
python
def add(a: int, b: int) -> int:
    """Add two numbers together.
    
    Args:
        a: First number
        b: Second number
        
    Returns:
        Sum of a and b
        
    Example:
        >>> add(2, 3)
        5
    """
    return a + b

Step 3: Generate Documentation

OpenAPI/Swagger:
bash
# Generate OpenAPI spec
npx swagger-jsdoc -d swaggerDef.js routes/*.js -o openapi.json

# Serve interactive docs
npx swagger-ui-express openapi.json
JSDoc:
bash
npx jsdoc src/ -d docs/ -r
Python Sphinx:
bash
sphinx-apidoc -o docs/source mypackage/
cd docs && make html
Python pdoc:
bash
pdoc --html --output-dir docs/ mypackage/

Step 4: Organize Output

Structure documentation:
docs/
├── api/
│   ├── openapi.json       # OpenAPI specification
│   ├── index.html         # Interactive API docs
│   └── endpoints/         # Endpoint details
├── reference/
│   ├── classes/           # Class documentation
│   ├── functions/         # Function documentation
│   └── types/             # Type definitions
└── guides/
    ├── authentication.md  # Auth guide
    └── examples.md        # Usage examples

Step 5: Add Examples

Include practical examples:
markdown
## Authentication

All API requests require authentication:

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

\`\`\`javascript
const response = await fetch('https://api.example.com/v1/users', {
  headers: { 'Authorization': 'Bearer TOKEN' }
});
\`\`\`

\`\`\`python
import requests

response = requests.get(
    'https://api.example.com/v1/users',
    headers={'Authorization': 'Bearer TOKEN'}
)
\`\`\`

OpenAPI Specification

Basic Structure

yaml
openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
  description: API description

servers:
  - url: https://api.example.com/v1

paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

Documentation Checklist

  • All endpoints documented
  • Request/response examples included
  • Authentication explained
  • Error codes documented
  • Rate limiting described
  • Code examples in multiple languages
  • Interactive API explorer available