usm/gen-openapi

OpenAPI 3.1 generator — produces an openapi.yaml spec and TypeScript types from feature .usm route and contract data.

Intent

API documentation must be machine-readable for SDK generation and testing. The OpenAPI generator extracts routes, HTTP methods, and contracts from feature files and produces a valid OpenAPI 3.1 spec plus generated TypeScript types.

Flows

Generate OpenAPI spec (gen-openapi-spec)

Produce openapi.yaml from feature routes and contracts

1. parse → all feature .usm files with routes
2. generate → paths, schemas, and operation objects
3. submit → write openapi.yaml and openapi-types.ts

Flow Diagrams

sequenceDiagram
    participant User
    participant Browser
    participant Server

    User->>Browser: parse all feature .usm files with routes
    User->>Browser: generate paths, schemas, and operation objects
    User->>Browser: submit write openapi.yaml and openapi-types.ts

Contracts

openapi-valid-spec

Generated OpenAPI spec must validate against the OpenAPI 3.1 schema

Acceptance criteria:

• [ ] All routes present as paths with correct HTTP methods
• [ ] Security schemes for auth-required routes
• [ ] TypeScript types generated for request/response schemas

Tests

openapi-has-routes

Given:

• features_with_api_routes: true

Then:

• assertion: openapi.yaml contains /api/* paths
• assertion: TypeScript types file generated

Implementation

• Primary: src/generators/openapi.ts
• Test code status: none

See Also

• usm/cli-generate