adding-api-docs

name	adding-api-docs
description	Generate OpenAPI/Swagger documentation for an API, including endpoint schemas, request/response types, and interactive docs UI.

Add API Documentation (OpenAPI)

Use this skill when the user asks to add API docs, Swagger, OpenAPI spec, or generate endpoint documentation.

Steps

1. Detect the API framework — check for Express, Fastify, Next.js API routes, Hono, Django REST Framework, FastAPI, etc.

2. For Node.js/Express — install swagger-jsdoc and swagger-ui-express:

   npm install swagger-jsdoc swagger-ui-express
   npm install -D @types/swagger-jsdoc @types/swagger-ui-express
   

   Create the OpenAPI spec from JSDoc annotations on route handlers:

   /**
    * @openapi
    * /api/users:
    *   get:
    *     summary: List all users
    *     responses:
    *       200:
    *         description: A list of users
    */
   

3. For Next.js API routes — create an openapi.json file manually or use next-swagger-doc to generate from route handlers. Serve the spec at /api/docs.

4. For FastAPI (Python) — docs are built-in at /docs (Swagger UI) and /redoc. Ensure Pydantic models are used for request/response types so schemas are auto-generated.

5. Add interactive docs UI — serve Swagger UI at a /docs route, or use Scalar/Redoc for a modern alternative:

   npm install @scalar/express-api-reference
   

6. Define schemas — create Zod schemas (or JSON Schema) for request bodies and responses, then reference them in the OpenAPI spec. For TypeScript projects, use zod-to-openapi to generate schemas from existing Zod validators.

7. Add authentication documentation — document the auth scheme (Bearer token, API key, OAuth2) in the OpenAPI securitySchemes section.

Notes

• Keep the spec in sync with the actual API — generate from code when possible rather than maintaining a separate YAML file.
• Add example values to schemas for better developer experience.
• Version the API docs alongside the code.