568 lines
12 KiB
Markdown
568 lines
12 KiB
Markdown
# API Documentation Generator Skill
|
|
|
|
Automatically generate comprehensive API documentation from code.
|
|
|
|
## OpenAPI 3.0 Generation
|
|
|
|
### From Express.js/TypeScript
|
|
|
|
```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
|
|
|
|
```yaml
|
|
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
|
|
```typescript
|
|
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)
|
|
```python
|
|
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
|
|
|
|
```markdown
|
|
# 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**:
|
|
```json
|
|
{
|
|
"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
|
|
```http
|
|
POST /users
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"email": "newuser@example.com",
|
|
"name": "New User",
|
|
"password": "SecurePass123!"
|
|
}
|
|
```
|
|
|
|
**Response 201**:
|
|
```json
|
|
{
|
|
"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:
|
|
```json
|
|
{
|
|
"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
|
|
```javascript
|
|
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
|
|
```python
|
|
import requests
|
|
|
|
response = requests.get(
|
|
'https://api.example.com/v1/users',
|
|
headers={'Authorization': f'Bearer {token}'}
|
|
)
|
|
data = response.json()
|
|
```
|
|
|
|
### cURL
|
|
```bash
|
|
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
|
|
|
|
1. **Be Comprehensive**: Document all endpoints, parameters, and responses
|
|
2. **Provide Examples**: Include real request/response examples
|
|
3. **Document Errors**: Show all possible error responses
|
|
4. **Code Samples**: Provide examples in multiple languages
|
|
5. **Keep Updated**: Auto-generate from code when possible
|
|
6. **Version APIs**: Include version in URL or headers
|
|
7. **Security**: Document authentication clearly
|
|
8. **Rate Limits**: Specify rate limiting rules
|
|
9. **Changelog**: Maintain API changelog
|
|
10. **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
|