mcpField
A
adding-api-docs

adding-api-docs

github.com/spencerpaulyDevelopment868419 installsUpdated 13w ago
Repository

About adding-api-docs

A skill for adding OpenAPI documentation to APIs across several frameworks. It guides framework detection, specification and schema creation, interactive docs, and authentication documentation.

Key features

  1. 01Detects the API framework
  2. 02Guidance for OpenAPI specification setup
  3. 03Schema definition and generation options
  4. 04Interactive documentation UI setup
  5. 05Authentication scheme documentation

Use cases

  1. 01Adding Swagger or OpenAPI docs to an API
  2. 02Publishing interactive endpoint documentation
  3. 03Documenting API request, response, and auth schemas

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/spencerpauly/awesome-cursor-skills --skill adding-api-docs

After installing, type/adding-api-docsin Claude Code to confirm it loaded.

Details

From the project README

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.

Comments

Markdown supported