API Documentation Generator
Quick Start
Generate API docs based on code type:
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 Type Tool Output
REST API OpenAPI/Swagger Interactive API docs
GraphQL GraphQL Schema Schema documentation
JavaScript Library JSDoc HTML reference
Python Library Sphinx/pdoc HTML reference
Step 2: Extract Documentation
REST API (OpenAPI):
Scan route files for JSDoc comments:
/**
- @swagger
- /users:
- get:
-
summary: Get all users -
responses: -
200: -
description: List of users
*/ router.get('/users', getUsers);
Generate spec:
npx swagger-jsdoc -d swaggerDef.js routes/*.js -o openapi.json
JavaScript Library (JSDoc):
/**
- 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):
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:
Generate OpenAPI spec
npx swagger-jsdoc -d swaggerDef.js routes/*.js -o openapi.json
Serve interactive docs
npx swagger-ui-express openapi.json
JSDoc:
npx jsdoc src/ -d docs/ -r
Python Sphinx:
sphinx-apidoc -o docs/source mypackage/ cd docs && make html
Python pdoc:
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:
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
openapi: 3.0.0 info: title: My API version: 1.0.0 description: API description
servers:
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