--- id: sm-api-documentation name: "api-documentation" url: https://skills.yangsir.net/skill/sm-api-documentation author: supercent-io domain: writing tags: ["openapi-(swagger)", "postman", "technical-writing", "api-reference", "markdown"] install_count: 11700 rating: 4.50 (468 reviews) github: https://github.com/supercent-io/skills-template --- # api-documentation > 该技能用于API开发过程中的文档编写，包括新端点添加、公共API发布、团队协作接口定义及内部参考，确保API清晰易懂。 **Stats**: 11,700 installs · 4.5/5 (468 reviews) ## Before / After 对比 ### 撰写高质量且易于理解的API文档，有效促进团队协作并加速外部系统集成进程 ## Readme # api-documentation 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 usageWeekly Installs11.1KRepositorysupercent-io/sk…templateGitHub Stars53First SeenJan 24, 2026Security AuditsGen Agent Trust HubPassSocketFailSnykPassInstalled oncodex11.0Kgemini-cli11.0Kopencode11.0Kgithub-copilot11.0Kcursor11.0Kamp10.9K --- *Source: https://skills.yangsir.net/skill/sm-api-documentation* *Markdown mirror: https://skills.yangsir.net/api/skill/sm-api-documentation/markdown*