route-to-openapi

# route-to-openapi Automatically scan route/endpoint definitions in source code and generate RESTful API documentation conforming to the [OpenAPI 3.0.3](https://spec.openapis.org/oas/v3.0.3) specification. Supports major web frameworks with automatic framework detection. Extracts HTTP methods, paths, parameters, request bodies, response models, and doc comments, then outputs a standard OpenAPI spec file ready to import into Swagger UI or Redoc. ## Quick Start ```bash # Scan source directory, output OpenAPI spec in JSON format python scripts/generate_api_doc.py ./src # Specify output format and file python scripts/generate_api_doc.py ./src --format yaml --output api-spec.yaml # Specify framework and API metadata python scripts/generate_api_doc.py ./app --framework flask --title "My API" --version 2.0.0 # Add server URLs python scripts/generate_api_doc.py ./routes --server http://localhost:3000 --server https://api.example.com ``` ## Supported Frameworks | Language | Framework | Parsing Method | |---|---|---| | Python | Flask | AST parsing (decorators + type annotations + docstrings) | | Python | FastAPI | AST parsing (decorators + Pydantic models + type annotations) | | Python | Django REST Framework | AST parsing (`@api_view` decorators) | | JavaScript/TypeScript | Express.js | Regex matching (`app.get()` / `router.get()` + JSDoc) | | Go | Gin | Regex matching (`r.GET()` / `group.GET()` + comments) | | Go | Echo | Regex matching (`e.GET()` + comments) | ## Extraction Capabilities The script automatically extracts the following information: - **HTTP Methods**: GET / POST / PUT / DELETE / PATCH, etc. - **Route Paths**: Automatically converts each framework's path parameter format to the OpenAPI `{param}` format - **Path Parameters**: Extracted from route patterns (with type inference) - **Query Parameters**: Extracted from function signatures (Python frameworks) - **Request Bodies**: Inferred from type annotations and Pydantic models (FastAPI) - **Response Models**: Extracted from the `response_model` parameter (FastAPI) - **Endpoint Descriptions**: Extracted from docstrings / JSDoc / inline comments - **Tag Grouping**: Automatically grouped by source file module name ## Path Parameter Format Conversion | Framework | Source Format | Converted Result | |---|---|---| | Flask | `<int:user_id>` | `{user_id}` (type: integer) | | FastAPI | `{user_id}` | `{user_id}` (unchanged) | | Express | `:user_id` | `{user_id}` | | Gin/Echo | `:user_id` | `{user_id}` | ## Parameters | Parameter | Description | Default | |---|---|---| | `source_dir` | Source directory to scan (required) | - | | `-f, --format` | Output format: `json` or `yaml` | `json` | | `-o, --output` | Output file path | stdout | | `--framework` | Force a specific framework (skip auto-detection) | Auto-detect | | `--title` | API documentation title | `API Documentation` | | `--version` | API version number | `1.0.0` | | `--description` | API description text | Empty | | `--server` | Server URL (can be specified multiple times) | None | ## Output Example ```json { "openapi": "3.0.3", "info": { "title": "My API", "version": "1.0.0" }, "paths": { "/users": { "get": { "summary": "List all users", "operationId": "list_users", "tags": ["users"], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful response" } } } }, "/users/{user_id}": { "get": { "summary": "Get user by ID", "operationId": "get_user", "tags": ["users"], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful response" } } } } } } ``` ## Prerequisites - Python 3.8+ - No additional dependencies required — uses only the Python standard library - The scanned project must use one of the supported web frameworks listed above