OpenAPI integration

How it works

Drop an OpenAPI 2.0 / 3.0 / 3.1 spec into your repo, point codiv.config.json at it, and CodivDocs auto-generates a full API reference for every endpoint. No template writing, no MDX per endpoint — the spec is the source of truth.

{
  "name": "Acme API",
  "api": {
    "openapi": "openapi.json",
    "playground": true
  },
  "navigation": [...]
}

URL pattern

Each endpoint becomes a page at:

/api-reference/{tag}/{operation-id}

The tag comes from the operation's tags[0] field (or default if none). The operation-id is the spec's operationId field (or a generated fallback like get-users-id if missing). Tags with spaces are slugified — "User Management" becomes user-management in the URL.

What's auto-generated

For every operation, the rendered page includes:

Supported spec versions

The parser uses @apidevtools/swagger-parser under the hood, which validates the spec and dereferences every $ref before we touch it. Invalid specs surface in your build log so you can fix them on the next push.

Schema features

Mixing manual MDX with auto-generated pages

The auto-generation only kicks in when there's no MDX page at the requested path. So you can override any auto-generated page by writing a manual MDX file at the same URL:

docs/api-reference/users/get-user.mdx

This wins over the auto-generated /api-reference/users/get-user. Use it when you want to add prose explanations, custom code examples, or migration notes that the spec alone can't express.

The recommended pattern: let auto-generation handle the bulk of your endpoints, write manual MDX only for the 5-10% that need extra context.

YAML support

YAML specs are not yet supported — the parser currently requires JSON. Two workarounds:

1. Convert to JSON: npx js-yaml openapi.yaml > openapi.json and commit the JSON

2. Use the framework preset (Phase 3.4 CLI, deferred to launch): tools like FastAPI, NestJS, Spring Boot, etc. emit JSON natively

Native YAML support is planned for a Phase 4 follow-up commit — it just adds a js-yaml dependency, no other changes.

Configure once, deploy forever

After your first push with api.openapi configured, the sync job auto-runs on every subsequent push. Update your spec, commit, push — the API reference updates 30 seconds later. No manual rebuild step.

Try it

If you have a working OpenAPI spec, drop it into your repo's root, add "api": { "openapi": "openapi.json" } to your codiv.config.json, and push. You'll have a fully-rendered API reference at /api-reference/{tag}/{operation-id} for every endpoint in your spec.

What's next