SKILL.md
API Documentation
When to use this skill
- API Development: When adding new endpoints
- External Release: Public API launch
- Team Collaboration: Frontend-backend interface definition
Instructions
Step 1: OpenAPI (Swagger) Spec
openapi: 3.0.0
info:
title: User Management API
version: 1.0.0
description: API for managing users
contact:
email: api@example.com
servers:
- url: https://api.example.com/v1
description: Production
- url: https://staging-api.example.com/v1
description: Staging
paths:
/users:
get:
summary: List all users
description: Retrieve a paginated list of users
tags:
- Users
parameters:
- name: page
in: query
schema:
type: integer
default: 1
- name: limit
in: query
schema:
type: integer
default: 20
maximum: 100
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/User'
pagination:
$ref: '#/components/schemas/Pagination'
'401':
$ref: '#/components/responses/Unauthorized'
post:
summary: Create a new user
tags:
- Users
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserRequest'
responses:
'201':
description: User created
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/BadRequest'
components:
schemas:
User:
type: object
properties:
id:
type: string
format: uuid
email:
type: string
format: email
name:
type: string
createdAt:
type: string
format: date-time
required:
- id
- email
- name
CreateUserRequest:
type: object
properties:
email:
type: string
format: email
name:
type: string
minLength: 2
maxLength: 50
password:
type: string
minLength: 8
required:
- email
- name
- password
Pagination:
type: object
properties:
page:
type: integer
limit:
type: integer
total:
type: integer
responses:
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "Authentication required"
BadRequest:
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: "Invalid input"
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
security:
- bearerAuth: []Step 2: Generate Documentation from Code (JSDoc/Decorators)
Express + TypeScript:
/**
* @swagger
* /api/users:
* post:
* summary: Create a new user
* tags: [Users]
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* required:
* - email
* - name
* - password
* properties:
* email:
* type: string
* format: email
* name:
* type: string
* password:
* type: string
* minLength: 8
* responses:
* 201:
* description: User created successfully
* 400:
* description: Invalid input
*/
router.post('/users', async (req, res) => {
const { email, name, password } = req.body;
const user = await userService.createUser({ email, name, password });
res.status(201).json(user);
});Step 3: Interactive Documentation
Swagger UI Setup:
import swaggerUi from 'swagger-ui-express';
import YAML from 'yamljs';
const swaggerDocument = YAML.load('./openapi.yaml');
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, {
customCss: '.swagger-ui .topbar { display: none }',
customSiteTitle: "My API Documentation"
}));Step 4: Examples & Guides
## API Documentation
### Authentication
All API requests require authentication using JWT tokens.
#### Getting a Token
\`\`\`bash
curl -X POST https://api.example.com/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com", "password": "yourpassword"}'
\`\`\`
Response:
\`\`\`json
{
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "..."
}
\`\`\`
#### Using the Token
\`\`\`bash
curl -X GET https://api.example.com/v1/users \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
\`\`\`
### Creating a User
**Endpoint**: `POST /v1/users`
**Request Body**:
\`\`\`json
{
"email": "john@example.com",
"name": "John Doe",
"password": "SecurePass123!"
}
\`\`\`
**Success Response** (201):
\`\`\`json
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"email": "john@example.com",
"name": "John Doe",
"createdAt": "2025-01-15T10:00:00Z"
}
\`\`\`
**Error Response** (400):
\`\`\`json
{
"error": "Email already exists"
}
\`\`\`
### Rate Limiting
- 100 requests per 15 minutes per IP
- Header: `X-RateLimit-Remaining`
### Pagination
\`\`\`
GET /v1/users?page=2&limit=20
\`\`\`
Response includes pagination info:
\`\`\`json
{
"data": [...],
"pagination": {
"page": 2,
"limit": 20,
"total": 157,
"pages": 8
}
}
\`\`\`
### Error Codes
- `400` - Bad Request (validation error)
- `401` - Unauthorized (missing/invalid token)
- `403` - Forbidden (insufficient permissions)
- `404` - Not Found
- `409` - Conflict (duplicate resource)
- `429` - Too Many Requests (rate limit)
- `500` - Internal Server ErrorOutput format
API Documentation Structure
docs/
├── README.md # Overview
├── getting-started.md # Quick start guide
├── authentication.md # Auth guide
├── api-reference/
│ ├── users.md # Users endpoints
│ ├── auth.md # Auth endpoints
│ └── products.md # Products endpoints
├── guides/
│ ├── pagination.md
│ ├── error-handling.md
│ └── rate-limiting.md
├── examples/
│ ├── curl.md
│ ├── javascript.md
│ └── python.md
└── openapi.yaml # OpenAPI specConstraints
Required Rules (MUST)
- Real Examples: Provide working code examples
- Error Cases: Document not only success but also failure cases
- Keep Updated: Update documentation when API changes
Prohibited (MUST NOT)
- Real Keys in Examples: Do not use real API keys/passwords in examples
- Vague Descriptions: Unclear descriptions like "returns data"
Best practices
- Try It Out: Provide interactive documentation (Swagger UI)
- Provide SDK: SDK and examples for major languages
- Changelog: Document API changes
References
Metadata
Version
- Current Version: 1.0.0
- Last Updated: 2025-01-01
- Compatible Platforms: Claude, ChatGPT, Gemini
Tags
#API-documentation #OpenAPI #Swagger #REST #developer-docs #documentation