adding-api-docs

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.

1. 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
    */

1. 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.

1. 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.

1. 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

1. 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.

1. 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.