skills.rest
zebbern
zebbernCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

route-to-openapi

Generate OpenAPI 3.0 specs by scanning route definitions in Flask, FastAPI, Express, and Go code.

4.6k|462|Updated Jun 21, 2025
Search Tags:#OpenAPI#FastAPI#Swagger#Flask#api documentation#Express#Code generation
One-click install
npx skills add https://github.com/zebbern/claude-code-guide --skill route-to-openapi
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: route-to-openapi
Source: https://github.com/zebbern/claude-code-guide/tree/main/skills/route-to-openapi
Command: npx skills add https://github.com/zebbern/claude-code-guide --skill route-to-openapi

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

Writing and maintaining OpenAPI documentation by hand is tedious and quickly drifts out of sync with the actual code. This Skill scans your existing route definitions and produces a standards-compliant OpenAPI 3.0.3 spec automatically, keeping API docs aligned with the implementation.

Core Features & Use Cases

  • Multi-Framework Route Scanning: Parses Flask, FastAPI, and Django REST Framework via Python AST, Express.js via regex with JSDoc, and Gin/Echo in Go via regex with comments.
  • Rich Endpoint Extraction: Captures HTTP methods, path parameters (with type inference), query parameters, request bodies, FastAPI response models, and docstring-based descriptions, then groups endpoints into tags by source file.
  • Flexible Output: Emits JSON or YAML specs with configurable title, version, description, and server URLs, ready to import into Swagger UI or Redoc.
  • Use Case: Point the script at a FastAPI project's source directory to instantly produce an api-spec.yaml documenting every endpoint, including Pydantic request/response models, for publishing to your developer portal.

Quick Start

Ask the assistant to scan your project's source directory and generate an OpenAPI 3.0 specification file from its route definitions.

Frequently Asked Questions about route-to-openapi

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I generate an OpenAPI spec from existing code?▼

Run the generate_api_doc.py script against your source directory, for example: python scripts/generate_api_doc.py ./src --format yaml --output api-spec.yaml. It auto-detects the framework, extracts routes, and writes a complete OpenAPI 3.0.3 spec.

Which web frameworks support automatic API documentation extraction?▼

The script supports Flask, FastAPI, and Django REST Framework in Python via AST parsing, Express.js in JavaScript/TypeScript via regex with JSDoc, and Gin and Echo in Go via regex with comments. Framework detection is automatic but can be forced with the --framework flag.

Does FastAPI response_model extraction work with Pydantic models?▼

Yes. The extractor reads the response_model decorator argument and type annotations, mapping Pydantic model classes to $ref entries under components/schemas in the generated spec. Request bodies are similarly inferred from annotated model parameters.

Can I convert Flask path parameters like <int:user_id> to OpenAPI format?▼

Yes. Flask converters such as <int:user_id> are converted to {user_id} with the appropriate schema type (integer, number, or string). Express and Gin :param syntax is also converted to the OpenAPI {param} format.

Why does the script report no routes found?▼

No routes are found when the source directory lacks supported framework code, files use dynamic route registration the static parser cannot match, or code sits in skipped directories like node_modules or venv. Verify the framework is supported and try forcing detection with --framework.

What are the limitations of static route extraction?▼

Static analysis cannot capture routes registered at runtime through dynamic logic, and Express or Go extraction relies on regex patterns rather than full parsing, so unconventional code styles may be missed. Django support is limited to @api_view decorators with inferred paths.

Related Skills

Explore More Software Engineering Skills→
bughqbughq
2

stacks-routes

Define and register route files with URL prefixes and middleware in Stacks applications.

Official
Intermediate
LKB-99LKB-99

api-documentation

Generate OpenAPI specifications and render interactive Swagger UI or Redoc docs.

Community
Advanced
datagouvdatagouv
13

siade-sync-openapi-payloads

Generate and validate SIADE staging payloads against OpenAPI schemas with rspec.

Official
Advanced
speakeasy-apispeakeasy-api
19

extract-openapi-from-code

Extract OpenAPI specifications from FastAPI, Flask, Django, and other codebases.

Official
Advanced