OpenAPI is a contract, not documentation

Many teams generate an OpenAPI file once to power a reference site, then stop maintaining it. Six months later the spec and the API disagree, and the docs quietly lie.

The contract mindset#

Treat the spec as the agreement between your API and its consumers. It becomes the input to more than docs:

• Server-side request validation
• Generated SDKs and mock servers
• Contract tests in CI
• The reference documentation

When the spec drives all of these, letting it drift breaks something visible.

Make drift a build failure#

Compare the running API against the spec in CI. A schema mismatch fails the build.

npx schemathesis run ./reference/openapi.yaml \
  --base-url https://sandbox.example.com \
  --checks all

Write for humans inside the spec#

The spec is also where reference prose lives. Good descriptions are specific:

# Weak
description: The project name.

# Strong
description: Display name shown in the dashboard. 1–80 characters. Must be unique within the workspace.

Examples are the documentation#

Readers copy examples before they read schemas. Add a realistic example to every request and response, and validate them against the schema so they can't rot.