baasith6/cursor-skills/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:

``bash 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:

```ts /**

• @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:

``bash 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.