Learn OpenAPI by example
One question per page. Each answer comes with an example that validates and the output of the tools that read it, and says when it was last checked.
OpenAPI reference
One keyword or pattern per page: what it means, an example that validates, and what tools do with it.
- $ref with a description next to it: OpenAPI 3.0 against 3.1
In OpenAPI 3.0 anything written next to a $ref is ignored, and linters report it. OpenAPI 3.1 allows keywords next to $ref in schemas, and summary and description next to other references. What changes, with the lint result for both versions.
- additionalProperties in OpenAPI: closed objects and maps
additionalProperties decides what happens to properties a schema does not name. false closes the object, a schema turns it into a map. Examples that validate, with a mock server's answers, and the allOf trap.
- allOf and parameters in OpenAPI: what works and what to write instead
allOf combines schemas, not parameters. It is valid inside a parameter's schema, and invalid as a way to merge a list of parameters. How to reuse a set of parameters, with the lint error the wrong form produces.
- enum in OpenAPI: allowed values, null, and adding one later
enum lists the values a field may take. How to write it, how to allow null, how to describe each value, and why adding a value to a response enum can break clients. With a mock server's answers.
- Error responses in OpenAPI: describing 4xx and 5xx with problem details
An operation that documents only its 200 leaves clients guessing what failure looks like. How to describe error responses once and reuse them, with the application/problem+json format of RFC 9457, a mock server's answers and the effect on a readiness score.
- example vs examples in OpenAPI: where each goes and which one tools use
example is one value, examples is a set. Their form depends on the place: a named map on a media type or parameter, a plain list in a 3.1 schema. Where each is allowed, which is deprecated, and which one a mock server answers with.
- nullable in OpenAPI 3.0 and 3.1: how to say a value may be null
OpenAPI 3.0 uses nullable: true. OpenAPI 3.1 removed it: write type: [string, "null"]. What to write in each version, what a linter and a breaking-change check say, and how to migrate.
- oneOf vs anyOf in OpenAPI: the one payload that tells them apart
oneOf needs exactly one schema to match, anyOf at least one. The difference only shows on a payload that fits two schemas: oneOf refuses it, anyOf accepts it. The same request sent to both, with a mock server's answers.
- operationId in OpenAPI: what it is for and how to name it
operationId is an optional, unique name for an operation. Code generators turn it into method names, documentation into links, tools into selectors. Naming rules that keep generated names predictable, with the linter's findings for the usual mistakes.
- readOnly and writeOnly in OpenAPI: one schema for requests and responses
readOnly marks a property the server sends and a client should not, writeOnly the reverse. They let one schema serve both directions. What the specification requires, and what a mock server actually does with each.
- The OpenAPI discriminator: what it does and what it does not
discriminator names the property that tells which oneOf schema a payload is. It helps code generators and documentation; it does not validate anything by itself. An example that validates, with a mock server's answers.
Errors and fixes
The message a linter, validator or mock server prints, the spec that causes it, and the fix.
- "Every operation must have unique operationId" (operation-operationId-unique)
Two operations share an operationId. The specification requires ids to be unique across the whole API; tools may use them to identify an operation, and some SDK generators turn them into method names. How to find the pair, and a naming scheme that does not collide.
- "invalid-ref ... does not exist" and "Can't resolve $ref": finding a broken reference
An OpenAPI $ref that points to nothing. How a linter and a bundler report it, how to read the path in the message, and the five usual causes: a typo, the wrong section, a moved file, a missing escape, a case difference.
- "must be equal to constant": a value that const does not allow
The schema fixes a property to one value with const, and the payload has another. Usually the discriminating field of a oneOf variant. How to find the expected value, and why the error often points at a variant you did not mean.
- "must be equal to one of the allowed values": an enum mismatch
The value is not in the schema's enum. The four usual reasons: a new value the description does not list yet, a difference in case, null missing from the enum, and a number sent as a string.
- "must be string", "must be integer": a value of the wrong type
The value's JSON type differs from the schema's type. Numbers in quotes, 1.5 for an integer, null for a non-nullable field, and why query parameters behave differently from a JSON body. With a mock server's answers.
- "must have required property": which property, where, and why
The payload lacks a property that the schema lists under required. How to read the pointer, why it appears in bulk under oneOf and anyOf, and the cases where the schema is wrong: readOnly fields and required with null.
- "must match exactly one schema in oneOf": what it means and how to fix it
The validator found that a value fits none of the oneOf schemas, or more than one. How to tell the two cases apart from the error list, and the three fixes: required, const and additionalProperties.
- "must NOT have additional properties": why a request is refused
The schema sets additionalProperties: false and the payload has a property it does not list. How to find which one, when the schema is wrong and not the payload, and the allOf combination that refuses every payload.
- "Operation must define parameter {id} as expected by path" (path-params)
A path contains {name} and the operation does not declare a path parameter of that name, or declares one the path does not contain, or forgets required: true. The four messages you usually see and the fix for each.
- "Operation must have non-empty "tags" array" (operation-tags)
A linter found an operation with no tags key or with tags: []. The document is valid in OpenAPI 3.0 and 3.1; the Spectral rule operation-tags warns because tags group operations in documentation. Add one tag per operation, or set the rule to off.
- "Potentially unused component has been detected" (oas3-unused-component)
A linter found a schema, parameter or response under components that nothing refers to. Why it is a warning, the three real causes (a leftover, a typo in a $ref, a component used from another file), and how to switch the rule off.
Guides
Tasks from start to finish: checks in CI, migrations, publishing.
- A GraphQL mock server from a schema file, in one command
apigit mock serve schema.graphql answers every query and mutation of an SDL schema at /graphql with generated values, and refuses queries the schema does not allow. What it returns, what it validates, and what it does not mock.
- A stateful mock server in JavaScript: answers that remember earlier requests
A mock generated from an API description answers each request on its own. When a test needs a cart that fills up or a user that exists after being created, write the routes as Express handlers and keep the data in a state object. A working example with its requests.
- Bundle a multi-file OpenAPI description into one file
Splitting an OpenAPI description over files keeps it maintainable; many tools still want one file. apigit bundle resolves the external $refs into components and leaves internal ones as references. A four-file example, the output, and why to lint the bundle.
- Lint an OpenAPI file in GitHub Actions, with each finding on its line
A short workflow that lints an OpenAPI description on every push and pull request, fails on errors and attaches each finding to its line as an annotation. The workflow, a failing pull request and a passing run from a real repository.
- Moving a Stoplight project to APIGit: what carries over, what to convert
A Stoplight project is OpenAPI files, JSON Schema models and Markdown in a known folder layout. The API files work unchanged; the sidebar file and Stoplight Flavored Markdown need converting. Each step, run on a sample project.
- Moving off Apiary: API Blueprint to OpenAPI, with docs and a mock server on the other side
Oracle announced the end of life of Apiary Cloud Service for 31 October 2026, and Apiary's hosted docs and mock servers no longer answer. The steps to move an API Blueprint description to OpenAPI, run on a sample: find the file, convert it, read what a linter says, mock it, publish it.
- Run a mock server from an OpenAPI file on your machine
One command starts a mock that answers every operation of an OpenAPI file with generated examples and refuses requests that do not match the description. What it returns, how it validates, and when to move it to a hosted mock.
Choosing a tool
Sourced comparisons of the tools that edit, document and mock an API description, row by row.
Try it with your own API
Create a free workspace, add an OpenAPI file, and publish its documentation and a mock server from the same repository.
Free for individuals. No credit card.
$ npm install -g @apigit/cli$ apigit auth login$ apigit doc publish