Openapi Spec Reference

An OpenAPI document is a YAML or JSON description of an HTTP API surface: paths, methods, parameters, request bodies, responses, and server variables. Engineering teams use it to generate client/server code, validate contracts before merge, drive automated tests, and keep documentation in sync with implementation. This reference collects the practical commands, configuration patterns, and failure modes you'll reach for when working with a spec in a daily development workflow.

Validating and Linting a Spec

Before a spec is merged or used to generate code, it should be checked against the OpenAPI grammar and a set of community‑maintained rules. The spectral CLI is a widely adopted tool for this; it reads an OpenAPI document and reports any violations of a configurable ruleset.

spectral lint openapi.yaml

The command exits with code 0 when every rule passes, and exits with code 1 when any rule is violated, printing each failure on stderr in the format:

✖ Rule Violation: no-unsupported-media-type at $.paths./pets.get.responses.200.content.application/json

(The exact rule name and JSON path depend on which rule is triggered.) To customize which checks run, create a .spectral.yaml file in the project root. A minimal configuration that enables the most common OpenAPI checks looks like this:

rules:
  no-unsupported-media-type: error
  no-duplicate-operations: error
  required-component-swagger: error

When spectral lint encounters a media type not registered in the OpenAPI 3.0 specification (for example application/vnd.custom+json without a proper encoding block), it reports the rule violation with the JSON pointer to the offending field, allowing the developer to add the type to the content map or register it as a vendor extension if intentionally novel.

Generating Server or Client Skeletons

Once a spec passes validation, the next routine step is producing a skeletal implementation in the language of choice. The openapi-generator utility reads an OpenAPI document and emits a full project skeleton for dozens of languages and frameworks.

openapi-generator generate -i openapi.yaml -g python-flask -o ./generated-server

The -i flag points at the spec file, -g selects the target generator (e.g. python-flask, node-express, csharp-dotnet), and -o sets the output directory. After the command completes, the ./generated-server directory contains a README, model classes, an API interface, and a stub server implementation.

To run the generated server, change into the output directory and use the language‑specific start command. For the python-flask generator this is typically:

cd ./generated-server
pip install -e .
python main.py

The stub server listening on http://localhost:8080 will respond to every declared endpoint, currently returning 501 Not Implemented on any path until the developer fills in the handler methods. The generator respects top‑level info, servers, and security blocks; however, any x- extensions present in the spec are passed through without interpretation by the generator, which means they will appear in the generated code as opaque data structures that the runtime ignores unless explicitly handled.

Testing Endpoints Against a Spec

After a server is running—whether generated from a spec or hand‑coded—verifying that the actual HTTP behaviour matches the description is a standard workflow. The simplest tool for this is curl, which is available on every development machine.

curl -i http://localhost:8080/pets

The -i flag includes the status line and response headers in the output, making it easy to confirm that the Content-Type declared in the spec (application/json) matches what the server actually sends.

A typical successful response for a GET /pets operation that declares a 200 with a Pet model containing id (integer) and name (string) might look like:

HTTP/1.1 200 OK
Content-Type: application/json
[ {"id": 1, "name": "dog"}, {"id": 2, "name": "cat"} ]

If the server returns a different status code, a mismatched Content-Type, or a JSON payload that omits or adds fields compared to the responses block, the discrepancy is usually caught by visual inspection. Some teams use a diff utility to compare recorded HTTP dumps against the spec; a dump is produced with curl -o response.json and then fed to a comparison script or pipeline step that lists paths, methods, or status codes where the observed response diverges from the spec's schema definition.

Version Migration and Format Concerns

OpenAPI has two major versions in circulation: the original Swagger 2.0 (written swagger: '2.0') and OpenAPI Specification 3.0 (written openapi: '3.0.0'). Most tooling targets one version at a time, and migration between them is a common one‑off task.

The @apidevtools/swagger-cli binary includes a convert subcommand that rewrites a Swagger 2.0 document into OpenAPI 3.0 format.

swagger-cli convert openapi-swagger.yaml > openapi3.yaml

The conversion maps paths, operations, parameters, and responses automatically, but a few differences require manual attention after the run:

• swagger: '2.0' produces and consumes arrays become openapi: '3.0.0' produces and consumes (deprecated in 3.0 in favor of the content map).
• Security schemes change from the top‑level apiKey, basic, or oauth2 blocks under swagger to the components.securitySchemes map in OpenAPI 3.0.
• x- extensions are preserved through the conversion but may carry different semantics depending on the generator consuming the document.

After conversion, running swagger-cli validate openapi3.yaml is the standard verification step to catch fields that the converter could not map or that violate the OpenAPI 3.0 grammar.

Sharp Edges: What Silently Goes Wrong

Even after a spec passes spectral lint or swagger-cli validate, several subtle issues can cause failures in production or during code generation.

• Server variable misconfiguration: If the spec defines a server object with a variable (servers: [{ url: "https://{api}.example.com", variables: { api: { default: "staging" } } }]) and the generator or test runner does not supply the variable value, the resolved URL may default to the literal string {api}.example.com or undefined, resulting in connection failures that are hard to trace in log output.
• Enum string mismatches: An enum field in a schema will cause the generator to emit typed constants, but if the runtime receives a value that is not one of the listed strings, the framework may reject the request with a 400 Bad Request before it reaches your handler. The spec itself does not enforce the enum at runtime; it is only a contract.
• Trailing commas in YAML: While many YAML parsers accept trailing commas, the OpenAPI 3.0 grammar is strict. A trailing comma in a paths map or a components block can cause swagger-cli validate to report a parsing error on certain parser versions, especially when the file is read by CI pipelines that use pyyaml in strict mode.
• x- extension collisions: Custom extensions prefixed with x- are ignored by the OpenAPI spec but may be consumed by generators or documentation tools. If two different teams use the same x- prefix for different purposes, the generated code can silently drop one set of extensions or, worse, merge them in an unexpected order, leading to missing or duplicated configuration at runtime.
• Optional versus required parameter collision: Declaring a parameter in parameters as in: query without required: true makes it optional, but some generators treat missing optional query strings as null rather than omitting the parameter entirely, leading to type errors in the stub server or unexpected 400 responses.
• HTTP status code overload: Listing the same status code multiple times under an operation’s responses map does not cause a validation error, but the last entry wins. If a 200 is defined twice with different schemas, the server will respond with the schema of the second entry, and the first is silently discarded.

These patterns are not tied to any particular product; they apply whenever an OpenAPI document is parsed, validated, or compiled by any tool that follows the specification grammar.

This page was rewritten on 14 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.