mcpField
A
adding-api-docs

adding-api-docs

github.com/revitalb-portDevelopment057 installsUpdated 10w ago
Repository

About adding-api-docs

A coding skill for adding OpenAPI documentation to web APIs. It guides agents through framework detection, spec and schema generation, interactive docs, and authentication documentation.

Key features

  1. 01Detects API frameworks
  2. 02Creates OpenAPI specifications
  3. 03Adds interactive documentation UI
  4. 04Defines request and response schemas
  5. 05Documents authentication schemes

Use cases

  1. 01Documenting an Express API with Swagger
  2. 02Adding API docs to Next.js routes
  3. 03Using built-in FastAPI documentation
  4. 04Keeping API specifications aligned with code

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/revitalb-port/skills-registry-demo --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