route-to-openapi skill

by zebbern·zebbern/claude-code-guide·4.6k stars·MIT

Generates RESTful API documentation (OpenAPI 3.0 / Swagger spec) by scanning route definitions in code for Flask, FastAPI, Express, Gin, and other frameworks. Trigger when users ask about API documentation, OpenAPI, Swagger, endpoint docs, generating docs from code, or extracting endpoints.

A100/100content scan

Is the route-to-openapi skill safe?

Clean: nothing in its files matched our rules. We read 3 files in the folder on 2026-09-28.

No findings.

Install the route-to-openapi skill

A skill is a folder. Copy it into your agent's skills folder and the agent loads it when the task matches its description.

git clone --depth 1 https://github.com/zebbern/claude-code-guide.git /tmp/claude-code-guide
mkdir -p ~/.claude/skills
cp -r /tmp/claude-code-guide/skills/route-to-openapi ~/.claude/skills/route-to-openapi

available in every project

In the Claude apps, zip the folder and upload it from the Skills settings. The folder on GitHub

The instructions your agent would load

SKILL.md as published, without the frontmatter. Read it on GitHub

route-to-openapi

Automatically scan route/endpoint definitions in source code and generate RESTful API documentation conforming to the OpenAPI 3.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

# 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

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

Parameters

Output Example

{
  "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

More skills from zebbern/claude-code-guide

Aacademic-paper-reviewerSimulates academic peer review, evaluating papers across Originality, Methodology, Results, and Writing to provide Major/Minor Revision recommendations with actionable feedback. Triggers when a user asks to \"review my paper,\" \"simulate peer review,\" or \"give my paper a peer review.
Aactive-directory-attacksThis skill should be used when the user asks to "attack Active Directory", "exploit AD", "Kerberoasting", "DCSync", "pass-the-hash", "BloodHound enumeration", "Golden Ticket", "Silver Ticket", "AS-REP roasting", "NTLM relay", or needs guidance on Windows domain penetration testing.
Capi-fuzzing-bug-bountyThis skill should be used when the user asks to "test API security", "fuzz APIs", "find IDOR vulnerabilities", "test REST API", "test GraphQL", "API penetration testing", "bug bounty API testing", or needs guidance on API security assessment techniques.
Aapi-shape-explorerGenerate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".
Aaudit-flowInteractive system flow tracing across CODE, API, AUTH, DATA, NETWORK layers with SQLite persistence and Mermaid export. Use for security audits, compliance documentation, flow tracing, feature ideation, brainstorming, debugging, architecture reviews, or incident post-mortems. Triggers on audit, trace flow, document flow, security review, debug flow, brainstorm, architecture review, post-mortem, incident review.
Aauthentication-patternsAuthentication patterns: session vs JWT vs OAuth comparison, provider selection (NextAuth, Clerk, Supabase Auth), security checklist, and common mistakes. Use when implementing auth, reviewing auth flows, or choosing auth providers.
Aaws-penetration-testingThis skill should be used when the user asks to "pentest AWS", "test AWS security", "enumerate IAM", "exploit cloud infrastructure", "AWS privilege escalation", "S3 bucket testing", "metadata SSRF", "Lambda exploitation", or needs guidance on Amazon Web Services security assessment.
Abroken-authenticationThis skill should be used when the user asks to "test for broken authentication vulnerabilities", "assess session management security", "perform credential stuffing tests", "evaluate password policies", "test for session fixation", or "identify authentication bypass flaws". It provides comprehensive techniques for identifying authentication and session management weaknesses in web applications.
Cburp-suite-testingThis skill should be used when the user asks to "intercept HTTP traffic", "modify web requests", "use Burp Suite for testing", "perform web vulnerability scanning", "test with Burp Repeater", "analyze HTTP history", or "configure proxy for web testing". It provides comprehensive guidance for using Burp Suite's core features for web application security testing.
AcachingCaching strategies — invalidation, TTL guidelines, cache keys, cache layers, and when not to cache. Use when implementing or reviewing caching logic.
Achart-imageGenerate publication-quality PNG chart images from data, supporting line, bar, area, candlestick, pie, and heatmap charts. Triggers when the user asks to visualize data, create a graph, plot a time series, or generate a chart for a report, alert, or dashboard. Runs as a lightweight, headless Node.js process without a browser.
Dcloud-penetration-testingThis skill should be used when the user asks to "perform cloud penetration testing", "assess Azure or AWS or GCP security", "enumerate cloud resources", "exploit cloud misconfigurations", "test O365 security", "extract secrets from cloud environments", or "audit cloud infrastructure". It provides comprehensive techniques for security assessment across major cloud platforms.

All agent skills → · MCP servers