Eve library

ISIS v2 WS10-001: Canonical OpenAPI Generation

Guide

Revision 1

On this page

Scope#

Implemented a canonical Isis OpenAPI artifact and generation gate so the published spec is generated from source route declarations.

Implemented Artifacts#

  • OpenAPI generator/check script:
    • scripts/isis/generate_generation_api_openapi.mjs
  • Canonical generated OpenAPI artifacts:
    • apps/isis/generation-api/openapi.yaml
    • openapi/isis/openapi.yaml
  • Generation API contract and script wiring:
    • apps/isis/generation-api/src/openapi.contract.spec.ts
    • apps/isis/generation-api/package.json
    • package.json

Generation Model#

  • Source-of-truth route extraction includes:
    • jobs routes (/api/v1/jobs/*)
    • models routes (/api/v1/models/*)
    • provider callback routes (/webhooks/*)
    • core health/queue aliases (/health, /ready, /api/v1/queue/stats)
  • Generator behavior:
    • preserves existing operation objects where available
    • inserts fallback operation objects for newly discovered routes
    • marks all operations with x-generated-from-source-route: true
    • emits identical YAML into service-local and canonical OpenAPI locations

Verification#

bash
node scripts/isis/generate_generation_api_openapi.mjs --check
pnpm --filter @isis/generation-api run openapi:check
pnpm --filter @isis/generation-api exec vitest run src/openapi.contract.spec.ts --reporter=dot

Outcome#

WS10-001 is now closed with deterministic, route-derived OpenAPI generation and a check gate that fails when published specs drift from source routes.