/generate-openapi

/api-architect:generate-openapi

Generate an OpenAPI 3.1 specification from the existing codebase or API design.

Process

1. Discover existing API routes and handlers:

• For Express/Fastify: search for `app.get`, `app.post`, `router.use` patterns
• For FastAPI/Flask: search for `@app.route`, `@router.get` decorators
• For Go: search for `http.HandleFunc`, `r.GET`, `mux.Handle` patterns
• For Spring: search for `@GetMapping`, `@PostMapping`, `@RestController` annotations
• Read each handler to understand request parameters, body, and response shape

2. Extract schema information:

• Parse TypeScript interfaces, Python dataclasses/Pydantic models, Go structs, or Java DTOs
• Map field types to OpenAPI types (string, integer, number, boolean, array, object)
• Identify required vs optional fields from type annotations or validation rules
• Extract enum values from code constants or type unions
• Document field constraints (minLength, maxLength, pattern, minimum, maximum)

3. Build the OpenAPI specification:

Info Section

• Set title from package.json name or project directory
• Set version from package.json version or git tag
• Write a concise description of the API's purpose

Servers

• Add localhost development server
• Add placeholder for production server URL

Paths

• One path entry per route
• Include all HTTP methods supported by each path
• Define path parameters with types and descriptions
• Define query parameters for list endpoints (pagination, filtering, sorting)
• Reference request body schemas from components
• Define response schemas for each status code (200, 201, 400, 401, 404, 500)

Components

• Define reusable schemas for each domain entity
• Create shared error response schema
• Create pagination metadata schema
• Define security schemes (Bearer JWT, API Key, OAuth2 as applicable)
• Use `$ref` extensively to avoid duplication

Security

• Apply security requirements globally or per-operation
• Document which endpoints are public (override global security with empty array)

4. Validate the specification:

• Ensure all `$ref` references resolve correctly
• Verify that every path parameter has a corresponding parameter definition
• Check that request bodies have content types specified
• Confirm response schemas match the actual handler return types

5. Generate example values for each schema to make the spec immediately testable.

Output

Write the specification to `openapi.yaml` (or `openapi.json` if the project prefers JSON). If an existing spec file is found, present a diff and ask before overwriting.

Rules

• Use OpenAPI 3.1.0 for JSON Schema compatibility
• Every endpoint must have a summary, description, and at least one response defined
• Use semantic operation IDs: `listUsers`, `getUserById`, `createOrder`
• Include realistic example values, not placeholder text like "string" or "0"
• Group related endpoints with tags matching the resource name
• Add `x-codegen` extensions if the project uses code generation tools
• Prefer YAML format for readability unless the project convention is JSON