api-docs-generator

API Documentation Generator

Generate clean, structured Markdown API reference docs from source code, OpenAPI/Swagger specs, or route definitions.

Gather Context

Before writing anything, determine:

1. Source — Controller, route file, OpenAPI spec (JSON/YAML), or a set of files?
2. API name — e.g., "User Management API". Infer from class/file name if not stated.
3. Base URL — e.g., https://api.example.com/v1. Default to https://api.example.com if unknown.
4. Auth method — Bearer token (default), API key, OAuth 2.0, or none.
5. Output format:
   • single-file (default) — one Markdown file with all endpoints
   • per-endpoint — one file per endpoint ({method}-{path-slug}.md) plus a README.md index
6. Language/framework — Auto-detect from file extensions, imports, and decorators.

If context is missing: In conversational mode, ask. In agent/inline mode, use sensible defaults and note your assumptions at the top of the output.

Analyzing the Source

From Source Code

Read the file(s) and extract:

• Every endpoint: HTTP method + route path
• Route params, query params, request body schemas
• Response types, status codes, and return models
• Auth requirements (per-endpoint if they vary)
• Doc comments, decorators, or annotations (/// <summary>, @ApiOperation, @app.get(...), JSDoc @param/@returns, etc.)

Framework detection hints:

Signal	Framework
[ApiController], [HttpGet]	ASP.NET Core
@app.get(), @router.post()	FastAPI
router.get(), app.use()	Express.js
@GetMapping, @RestController	Spring Boot
@Controller, @Get()	NestJS
resources :users	Rails

From OpenAPI/Swagger Specs

Parse the spec and map directly:

• paths → endpoints
• parameters → params table
• requestBody → request body section
• responses → response table + examples
• components/schemas → inline the referenced models
• securityDefinitions / securitySchemes → auth section
• info.title, info.version, servers[0].url → header metadata