- 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 Error
- Output 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 spec
- Constraints
- 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
- OpenAPI Specification
- Swagger UI
- Redoc
- 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
Examples Example 1: Basic usage Example 2: Advanced usage