Api Docs Gen

Convert source code into OpenAPI 3.0 specs or Markdown docs via static analysis of Express, FastAPI, and more.

Install
cmdop skills install agensi-api-docs-gen

Api Docs Gen is a skill that performs static analysis on backend source code to produce API documentation without manual entry or API keys. It scans file systems, recognizes framework-specific routing patterns, and infers request and response shapes from TypeScript interfaces, Zod schemas, Pydantic models, and JSDoc comments.

Framework support covers Node.js runtimes including Express, Next.js, Hono, and Koa, as well as Python frameworks including FastAPI, Flask, and Django REST. The skill automatically detects protected routes by identifying authentication middleware such as JWT, Passport, and FastAPI Dependencies, then records those requirements in the output.

Output is available in two formats: valid OpenAPI 3.0 YAML suitable for use with Swagger UI, Redoc, and Postman, and GitHub-flavored Markdown suitable for READMEs and internal wikis. When explicit type annotations are absent, the skill applies naming-convention heuristics to infer types.

This skill is appropriate when a codebase has grown without up-to-date documentation, when onboarding new contributors who need accurate endpoint references, or when a CI step should regenerate specs after code changes. It is not a linting or testing tool and does not validate that the documented endpoints behave correctly at runtime. No environment variables or credentials are required to run it.

Use cases

  • Generate an OpenAPI 3.0 YAML spec from an existing Express or FastAPI codebase with no manual Swagger annotations
  • Produce Markdown endpoint references for a README or internal wiki after adding new routes
  • Identify and document which routes are protected by JWT or Passport middleware
  • Infer request and response schemas from Zod schemas or Pydantic models without writing OpenAPI by hand
  • Regenerate API docs in a CI pipeline after each backend code change
  • Prepare Postman-compatible OpenAPI specs for a team's QA or integration testing workflow

When to use it

  • The backend uses Express, Next.js, Hono, Koa, FastAPI, Flask, or Django REST and documentation is missing or stale
  • Schemas are defined via TypeScript interfaces, Zod, Pydantic, or JSDoc and need to be reflected in the spec
  • Both OpenAPI YAML and Markdown output formats are needed from the same source
  • No API keys or external credentials are available to run a runtime introspection tool

When not to use it

  • The backend framework is not among the supported Node.js or Python frameworks listed in the facts
  • Runtime validation of endpoint behavior is required — this skill performs static analysis only
  • The project requires documentation formats other than OpenAPI 3.0 YAML or GitHub-flavored Markdown
  • GraphQL or gRPC APIs need to be documented — no support for those is stated in the facts