---
name: api-docs
description: "Generate OpenAPI 3.1 documentation from your API codebase. Auto-detects Express, Fastify, NestJS, Django, FastAPI, Flask, Rails, Spring, Go, and more. Extracts routes, request/response schemas, auth requirements, and validation rules. Sets up interactive docs with Swagger UI, Redoc, or Scalar. Use when you need API documentation, OpenAPI spec, Swagger docs, endpoint reference, or REST API docs."
version: "2.0.0"
category: docs
platforms:
  - CLAUDE_CODE
---

You are in AUTONOMOUS MODE. Do NOT ask questions. Analyze the project's API
layer and produce complete OpenAPI documentation.

INPUT:
$ARGUMENTS

If no arguments provided, auto-detect the API framework and document all endpoints.
If a specific path, module, or endpoint group is provided, scope documentation to that area.

============================================================
PHASE 1: FRAMEWORK DETECTION
============================================================

Detect the API framework by scanning for config files and import patterns:

| Framework | Detection Signals |
|-----------|------------------|
| Express | `require('express')`, `import express`, `app.get(`, `router.post(` |
| Fastify | `require('fastify')`, `import Fastify`, `fastify.route(`, `fastify.get(` |
| NestJS | `@Controller(`, `@Get(`, `@Post(`, `nest-cli.json` |
| Hono | `import { Hono }`, `new Hono()`, `app.get(` with Hono types |
| Django REST | `urls.py`, `views.py`, `serializers.py`, `rest_framework` imports |
| FastAPI | `from fastapi`, `@app.get(`, `@router.post(`, `APIRouter` |
| Flask | `from flask`, `@app.route(`, `Blueprint` |
| Go net/http | `http.HandleFunc(`, `http.ListenAndServe(`, `mux.Handle(` |
| Gin | `gin.Default()`, `r.GET(`, `r.POST(` |
| Rails | `routes.rb`, `config/routes`, `resources :` |
| Spring | `@RestController`, `@RequestMapping`, `@GetMapping` |
| ASP.NET | `[ApiController]`, `[HttpGet]`, `MapGet(`, `app.MapControllers()` |

Record the detected framework as API_FRAMEWORK for subsequent phases.

If no API framework is detected, check for:
- GraphQL schemas (schema.graphql, typeDefs)
- gRPC proto files (*.proto)
- WebSocket handlers
- Serverless function handlers (Lambda, Cloud Functions)

Report the finding and adapt accordingly.

============================================================
PHASE 2: ROUTE EXTRACTION
============================================================

Systematically extract all API routes:

Step 2.1 -- Find Route Files

Based on API_FRAMEWORK, locate route definitions:
- Express/Fastify/Hono: scan for `router.`, `app.get/post/put/delete/patch`
- NestJS: scan for `@Controller` decorated classes
- Django REST: read all `urls.py` files and `viewsets`
- FastAPI: scan for `@app.` and `@router.` decorators
- Go: scan for `HandleFunc`, `Handle`, `mux.` calls
- Rails: read `config/routes.rb`
- Spring: scan for `@RequestMapping`, `@GetMapping`, etc.

Step 2.2 -- Extract Route Details

For each route, extract:
- HTTP method (GET, POST, PUT, PATCH, DELETE)
- Path pattern (including path parameters like `:id` or `{id}`)
- Handler function name and file location
- Middleware chain (auth, validation, rate limiting)
- Request body schema (from validation libraries, DTOs, or type annotations)
- Response schema (from return types, serializers, or response helpers)
- Query parameters (from parsing logic or decorators)
- Path parameters and their types
- Status codes returned (from explicit responses and error handlers)

Step 2.3 -- Extract Authentication Requirements

Identify auth patterns:
- JWT middleware / Bearer token checks
- API key validation
- Session/cookie auth
- OAuth scopes
- Role-based access control (RBAC) decorators or middleware
- Public vs protected routes

Step 2.4 -- Extract Validation Schemas

Look for request validation:
- Zod schemas
- Joi schemas
- class-validator decorators (NestJS)
- Pydantic models (FastAPI)
- JSON Schema definitions
- TypeScript interfaces/types used for request/response
- Django serializers

============================================================
PHASE 3: OPENAPI SPEC GENERATION
============================================================

Generate an OpenAPI 3.1.0 specification:

Generate a valid OpenAPI 3.1.0 YAML spec with: info (title, description, version
from package config), servers (localhost with detected port), paths (from extracted
routes), components/schemas (from extracted types), and securitySchemes.

For each path item include: operationId, summary, description, tags (grouped by
controller/router or URL prefix), parameters, requestBody, responses with status
codes, and security requirements.

For schemas: convert TypeScript interfaces, Pydantic models, Zod schemas, or Django
serializers to JSON Schema. Mark required vs optional fields. Include examples from
test fixtures or seed data where available. Generate both success and error examples.

============================================================
PHASE 4: INTERACTIVE DOCS SETUP
============================================================

Set up interactive API documentation:

Step 4.1 -- Choose Tool

Based on the framework and existing dependencies:

| Condition | Tool | Setup |
|-----------|------|-------|
| Fastify project | @fastify/swagger + @scalar/fastify-api-reference | Plugin registration |
| Express project | swagger-ui-express | Middleware mount |
| NestJS project | @nestjs/swagger | Module configuration |
| FastAPI project | Built-in (Swagger UI at /docs) | Already available |
| Django REST | drf-spectacular or drf-yasg | Settings configuration |
| Any project | Redoc standalone | Static HTML page |
| Any project | Scalar | CDN-based HTML page |

Step 4.2 -- Integration

If the project supports it, add interactive docs as a development dependency:
- Install the appropriate package
- Add the route/middleware to serve docs (typically at /docs or /api-docs)
- Configure to load the generated OpenAPI spec
- Add a script to package.json or equivalent to regenerate the spec

If the project does not support middleware-based docs, generate a standalone
HTML file using Scalar or Redoc CDN that references the spec file.

============================================================
PHASE 5: VALIDATION
============================================================

Validate the generated spec against the actual codebase:

Step 5.1 -- Route Coverage

- Count total routes extracted from code
- Count total paths in generated spec
- Flag any routes missing from the spec
- Flag any spec paths that do not match actual routes

Step 5.2 -- Schema Accuracy

- Compare generated request schemas against validation middleware
- Compare generated response schemas against actual handler return values
- Flag mismatches or missing schemas

Step 5.3 -- Spec Lint

- Verify the spec is valid OpenAPI 3.1.0
- Check for missing descriptions on operations
- Check for missing response schemas
- Check for undocumented error responses


============================================================
SELF-HEALING VALIDATION (max 2 iterations)
============================================================

After producing documentation, validate completeness:

1. Verify all required sections are present and non-empty.
2. Verify internal cross-references and links resolve correctly.
3. Verify no placeholder text remains ("{TODO}", "[TBD]", "...", "etc.").
4. Verify code examples are syntactically valid.

IF VALIDATION FAILS:
- Identify which sections are incomplete or contain placeholders
- Re-generate only the deficient sections
- Repeat up to 2 iterations

============================================================
OUTPUT
============================================================

Write the following files:

1. `docs/openapi.yaml` -- The complete OpenAPI 3.1.0 specification
2. `docs/api-docs.md` -- Human-readable API reference (for GitHub browsing)

Report:

## API Documentation Generated

### Framework
- **Detected:** [framework name and version]
- **API Style:** REST / GraphQL / gRPC / Mixed

### Coverage
- **Total Routes:** N
- **Documented:** N
- **Missing Docs:** N (list any gaps)

### Files Created
- `docs/openapi.yaml` -- OpenAPI 3.1.0 specification
- `docs/api-docs.md` -- Markdown API reference

### Interactive Docs
- **Tool:** [Swagger UI / Redoc / Scalar / Built-in]
- **URL:** [localhost:PORT/docs or path to HTML file]
- **Setup:** [any manual steps needed]

### Endpoint Summary

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | /api/users | Bearer | List all users |
| POST | /api/users | Bearer | Create a user |
| ... | ... | ... | ... |

### Validation Results
- Schema mismatches: [list or "none"]
- Missing response docs: [list or "none"]
- Undocumented error codes: [list or "none"]


============================================================
SELF-EVOLUTION TELEMETRY
============================================================

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:
- Look for the project path in `~/.claude/projects/`
- If found, append to `skill-telemetry.md` in that memory directory

Entry format:
```
### /api-docs — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}
```

Only log if the memory directory exists. Skip silently if not found.
Keep entries concise — /evolve will parse these for skill improvement signals.

============================================================
DO NOT
============================================================

- Do NOT fabricate endpoints. Only document routes found in the actual code.
- Do NOT include internal/private routes unless they are part of the API surface.
- Do NOT hardcode example API keys, tokens, or secrets in examples.
- Do NOT overwrite an existing OpenAPI spec without reading it first and
  preserving any manually-written descriptions or examples.
- Do NOT install packages in production dependencies -- docs tools go in devDependencies.
- Do NOT generate docs for test endpoints or health checks unless they are
  part of the documented API surface.

NEXT STEPS:

After generating API documentation:
- "Run `/document` to audit overall documentation coverage."
- "Run `/qa` to verify API endpoint behavior matches the spec."
- "Run `/secure` to audit API security (auth, rate limiting, input validation)."