api-documentation

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