API Documentation

API Documentation

Skill Purpose: API documentation generation, OpenAPI specification management, and interactive documentation patterns

---

Core Skill Pattern

Objective: Establish comprehensive API documentation with OpenAPI specifications, interactive documentation, and type-safe client generation.

Universal Pattern:

1. Define API documentation standards and specifications
2. Create OpenAPI schema generation patterns
3. Set up interactive documentation and exploration
4. Establish client code generation procedures
5. Create documentation maintenance and versioning

Key Decisions (Project-Specific):

• Documentation format and specification version
• Interactive documentation tool and configuration
• Client generation depth and language support
• Documentation hosting and accessibility
• Versioning and maintenance procedures

---

Project-Specific Implementation Notes

Customize per project:

• Documentation format based on API complexity and stakeholder needs
• Interactive tool based on team preferences and deployment
• Client generation based on frontend requirements
• Hosting approach based on security and accessibility needs
• Maintenance depth based on API stability and change frequency

---

Example Implementation (OpenAPI Documentation Pattern)

Note: This is an example pattern using OpenAPI with Swagger UI. Adapt documentation format and tools based on your specific project requirements and API architecture.

Prerequisites (Example)

• API endpoints designed and implemented
• Request/​response schemas defined
• Documentation requirements established

---

Example: API Documentation Implementation

Framework-Specific Example: This demonstrates OpenAPI documentation patterns. Adapt for your documentation format and API requirements.

Installation

npm install next-swagger-doc swagger-ui-react

Configuration

// lib/​swagger.ts
import { createSwaggerSpec } from 'next-swagger-doc';

export const getApiDocs = async () => {
  const spec = createSwaggerSpec({
    apiFolder: 'app/​api',
    definition: {
      openapi: '3.0.0',
      info: {
        title: 'Project API',
        version: '1.0.0',
      },
      components: {
        securitySchemes: {
          bearerAuth: {
            type: 'http',
            scheme: 'bearer',
          },
        },
      },
    },
  });
  return spec;
};

Documenting Endpoints

// app/​api/​users/​route.ts

/​**
 * @swagger
 * /​api/​users:
 *   get:
 *     summary: Get all users
 *     tags: [Users]
 *     security:
 *       - bearerAuth: []
 *     responses:
 *       200:
 *         description: List of users
 *         content:
 *           application/​json:
 *             schema:
 *               type: array
 *               items:
 *                 $ref: '#/​components/​schemas/​User'
 */
export async function GET() {
  // implementation
}

---

Schema Definitions

/​**
 * @swagger
 * components:
 *   schemas:
 *     User:
 *       type: object
 *       required:
 *         - id
 *         - email
 *       properties:
 *         id:
 *           type: string
 *           format: uuid
 *         email:
 *           type: string
 *           format: email
 *         name:
 *           type: string
 */

---

Best Practices

1. Document all public endpoints - Every API route should have OpenAPI comments
2. Use tags for grouping - Group related endpoints by resource
3. Include examples - Provide request/​response examples
4. Document errors - Include all possible error responses
5. Keep schemas in sync - Align with Zod schemas and database types

---

Stop Conditions

STOP and escalate if:

• Endpoint behavior unclear
• Response schema not defined
• Authentication requirements undefined

---

Skill Version: 1.0.0