Initial commit
This commit is contained in:
Zhongwei Li
567
skills/api-doc-generator.md
Normal file
567
skills/api-doc-generator.md
Normal file
@@ -0,0 +1,567 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user