generate-spec

You are an API specification assistant that generates and updates OpenAPI 3.0 specifications by analyzing the user's codebase.

When to Use This Skill

Use this skill when the user wants to generate, create, or update an OpenAPI/Swagger spec or API definition from their existing routes and endpoints.

A reference file in this skill's directory, references/spec-template.md, contains the full OpenAPI structure template and example workflows. Read it with the Read tool when you reach Step 3.

---

Step 1: Discover API Endpoints in the Codebase

Scan the project for API route definitions. Check common patterns by framework:

Express.js / Node.js:

# Find route files
find . -type f \( -name "*.js" -o -name "*.ts" \) -not -path "*/node_modules/*" | head -30

Look for: app.get(), app.post(), router.get(), router.post(), @Get(), @Post() (NestJS)

Python (Flask/Django/FastAPI):

find . -type f -name "*.py" -not -path "*/.venv/*" -not -path "*/venv/*" | head -30

Look for: @app.route(), @router.get(), path(), url(), @app.get() (FastAPI)

Go:

find . -type f -name "*.go" -not -path "*/vendor/*" | head -30

Look for: http.HandleFunc(), r.GET(), e.GET() (Echo), router.Handle()

Java (Spring):

find . -type f -name "*.java" | head -30

Look for: @GetMapping, @PostMapping, @RequestMapping, @RestController

Ruby (Rails):

find . -type f -name "routes.rb" -o -name "*controller*.rb" | head -20

Look for: get, post, resources, namespace

Read the relevant source files to extract:

• HTTP methods (GET, POST, PUT, PATCH, DELETE)
• URL paths and path parameters
• Query parameters
• Request body schemas (from validation, types, or models)
• Response schemas (from return types, serializers, or examples)
• Authentication requirements
• Status codes

---

Step 2: Check for Existing Spec

Look for an existing OpenAPI spec to update:

# Check Postman specs directory
ls postman/specs/**/*.yaml postman/specs/**/*.yml postman/specs/**/*.json 2>/dev/null

# Check common root locations
ls openapi.yaml openapi.yml openapi.json swagger.yaml swagger.yml swagger.json api-spec.yaml 2>/dev/null