Model a polymorphic response with a discriminator
Describe a response that comes in several shapes so a generator emits a tagged union rather than a bag of optional fields, using oneOf with a discriminator.
How-to › Section 5
Describe your API#
Authoring, linting, modelling and versioning the description that SDKs, docs and agent surfaces are generated from, including letting a coding agent draft or repair it.
7 guides in 6 topics. Every guide compares its approaches and shows the output its commands printed.
- Write an OpenAPI description 2
- Author or repair a spec with a coding agent 1
- Lint and govern API specs 1
- Model resources, relations and actions 1
- Extract a semantic model from a spec 1
- Version and retire APIs 1
Write an OpenAPI description 2 guides
Writing OpenAPI 3.1 that tools can use: operationIds (snake_case, unique, verb plus noun, one page on ids that generate clean SDK method names), tags, components and $ref reuse, discriminators, nullable versus unions, examples, security schemes, servers, webhooks and callbacks, uploads, bundling and splitting, Swagger 2 to 3.1 migration, design-first versus code-first (FastAPI, NestJS Swagger, springdoc, swag, zod-openapi, Huma, tsoa).
Split and bundle a large OpenAPI document
Break a multi-thousand-line description into per-resource files, then produce the single bundled document most generators expect, without losing component names.
Author or repair a spec with a coding agent 1 guide
The spec as an output of AI, not only an input: drafting an OpenAPI description with Claude Code, Cursor or Copilot from route handlers, from HAR captures, from prose docs or a Postman collection; filling missing schemas and examples; repairing a spec that a generator rejects; validating the result with Spectral, Schemathesis and a mock server; keeping the agent-written spec in sync with code in CI.
Fill missing schemas and examples with a coding agent
List every response with no schema or example with two Spectral rules, hand the gaps and fixtures to a coding agent, and validate every example after every batch.
Lint and govern API specs 1 guide
Style rules and governance: Spectral rulesets and custom functions, Redocly lint, Stoplight style guides, vacuum, CI gates, checks that generated SDKs will be usable (every operation has an id, every response has a schema), conventions across many services.
Enforce a naming convention across 40 microservice specs
Run one naming ruleset in every repository, then compare terms across specs, because no per-document linter sees that billing says customer and CRM says client.
Model resources, relations and actions 1 guide
Designing the resource model before or beside the spec: resource naming, id formats, sub-resources versus links, non-CRUD actions such as cancel or approve, filtering and sorting, field selection, relationships, deciding when an endpoint is an entity operation and when it is a standalone action.
Decide if an endpoint is an entity operation or an action
Apply one test to every proposed endpoint, tabulate the verdicts, and catch the PATCH that refunds a card and sends an email while looking like a safe update.
Extract a semantic model from a spec 1 guide
Turning endpoints into entities, attributes and operations: classification heuristics (which path is a list, load, create, update or remove), handling endpoints that map to no entity (direct and prepare escape hatches), flows, inconsistent specs, diffing two models from successive spec versions, publishing the model as JSON beside OpenAPI, and verifying that SDK, CLI and MCP server were generated from the same model version.
Reconcile an extracted entity model with a domain model
Put the entity model extracted from the spec beside the one your team drew, give each disagreement a row and a decision, and fail the build when one has neither.
Version and retire APIs 1 guide
Versioning strategies (path, header, date-based as Stripe does), additive change rules, breaking-change detection in CI (oasdiff, openapi-diff, Optic, and aontu breaking and subsume as one option for model files), Sunset and Deprecation headers, deprecation calendars, compatibility tests, and tying SDK versions to API versions (the sdkgen api-versioning design note as one approach beside Stainless and Speakeasy).
Pin an API version from a client
Send the API version you were built against on every request, and refuse a response that came back under a different one.
Generate the client instead of writing it#
Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.