OpenAPI 3.1 spec examples: endpoints, schemas, auth, and validation

Three distinct versions of the OpenAPI specification are in active use, and they are not backward-compatible. Swagger 2.0, released in 2014, uses the swagger key and organizes request bodies as parameters with in: body. OpenAPI 3.0.x, released in 2017, introduced the openapi key, replaced in-body parameters with the dedicated requestBody field, moved servers out of basePath, and reorganized reusable definitions under components. OpenAPI 3.1.0, released in 2021, aligned the schema dialect with full JSON Schema draft 2020-12, which means features like unevaluatedProperties and if/then/else are now valid.

The most common source of confusion is mixing version-specific syntax. A developer who writes openapi: 3.0.0 at the top and then writes parameters with in: body below it produces a spec that fails validation but may pass some lenient parsers. Swagger UI sometimes renders both syntaxes without flagging the inconsistency, masking the problem until a code generation tool or strict validator rejects the spec.

YAML and JSON are both valid formats for OpenAPI specs. YAML is preferred by most teams because it is easier to read and write by hand, supports comments, and avoids the visual noise of JSON curly braces and quotes. JSON is easier to generate programmatically and parse with standard libraries. A significant YAML gotcha is unquoted status codes: writing 200: instead of "200": causes YAML to parse the key as an integer, which some parsers reject because OpenAPI requires status codes to be strings.

The required field in object schemas is not optional. Without it, all properties are treated as optional by code generators. A User schema with properties for name and email but no required: [name, email] produces TypeScript types where both fields are optional, which does not match the server behavior. Always define required for every schema that has mandatory properties.

OpenAPI 3.1 is still not universally supported. Redoc added 3.1 support in version 2.0. Swagger UI has partial support. Many code generation tools, including openapi-generator-cli, have mixed support for 3.1-specific features. If maximum toolchain compatibility is required, OpenAPI 3.0.3 remains the safer choice until tooling catches up.

Two tools cover different levels of spec correctness. swagger-cli validate checks structural validity: required fields, correct types, and resolvable dollar-ref references. It catches most syntactic errors. Spectral lint applies rule-based checks that go beyond syntax into API design quality: missing operationId, undefined response schemas, inconsistent naming conventions, and missing examples.

Run swagger-cli validate openapi.yaml first. If it reports errors, fix them before running Spectral because Spectral errors are harder to interpret when the spec has structural problems underneath. The swagger-cli tool is available via npm: npm install -g @apidevtools/swagger-cli.

Install Spectral with npm install -g @stoplight/spectral-cli and create a .spectral.yaml configuration file at the repository root. The minimal configuration that catches common problems looks like: extends: ["spectral:oas"] with selected rules enabled. The oas ruleset catches missing operationId, undefined response content, and dollar-ref resolution failures.

For finding dollar-ref errors, swagger-cli bundle openapi.yaml --outfile bundled.yaml is useful. It resolves all references into a single file. If any reference fails to resolve, the bundle step fails with an explicit error pointing to the broken path. This is faster than reading Spectral output for large specs.

For code generation validation, run openapi-generator-cli generate and inspect the generated types. Missing required arrays show up as optional types. Missing response schemas show up as any or object types. Missing operationId values cause code generators to invent method names based on the path and method, which are often verbose and inconsistent.

Test the actual endpoints described in the spec using /tools/http-request-builder to verify that server behavior matches the spec. A spec that validates correctly but does not match the server's actual behavior will produce generated clients that fail at runtime. Spec-first development closes this gap by using the spec to generate server stubs, ensuring alignment by construction.

The dollar-ref mechanism is the most powerful feature for keeping large OpenAPI specs maintainable. Without dollar-ref, every endpoint must inline the full schema for every request and response. With dollar-ref, a User schema defined once in components/schemas/User can be referenced from every operation that returns a user, from list endpoints that return arrays of users, and from create and update endpoints that accept user data.

A dollar-ref must be an exact JSON Pointer to a definition within the spec or an external file. The local reference format is $ref: "#/components/schemas/User" where the leading hash means the root of the current document. The path segments are separated by forward slashes. A typo in any segment silently omits the referenced schema in some tools or produces an error in strict validators. Use the swagger-cli bundle step to catch broken references early.

Components has several subsections. components/schemas holds data model definitions. components/responses holds reusable response definitions including status code, headers, and content. components/parameters holds reusable query, path, and header parameters. components/examples holds example values for documentation. components/securitySchemes holds authentication definitions.

For security schemes, three types cover most cases. Bearer JWT uses type: http, scheme: bearer, bearerFormat: JWT. API key in the Authorization header uses type: apiKey, in: header, name: X-API-Key. OAuth2 authorization code uses type: oauth2 with a flows.authorizationCode field containing authorizationUrl and tokenUrl. Define the scheme once in components/securitySchemes and apply it globally with a top-level security field. Override it per-operation to mark public endpoints with security: [].

For polymorphic responses where the shape depends on a discriminator field, use oneOf with a discriminator key. The discriminator specifies which property in the response object determines the concrete type. Code generators use this information to produce union types in TypeScript and sealed classes in Kotlin. allOf is for merging schema definitions, not for expressing exclusive type alternatives. Using allOf for polymorphism generates incorrect types that combine all properties from all variants.

For validation errors, define a single ValidationError component and reference it from every 422 response. Keeping the error schema in one place ensures the error format is consistent across all endpoints, which simplifies client error handling.

The nullable field behaves differently between OpenAPI 3.0.x and 3.1. In OpenAPI 3.0.x, nullable: true is a non-standard extension that indicates a property can be null. In OpenAPI 3.1, which aligns with JSON Schema, the correct way to express nullability is type: [string, null] using a type array. Tools that validate against 3.0 will reject the array form, and tools that validate against 3.1 will report a warning for nullable: true as a deprecated non-standard extension.

readOnly and writeOnly properties allow you to define properties that appear only in responses or only in requests respectively. A User schema with a createdAt property that is readOnly: true indicates the field should not be included in POST or PUT request bodies. Code generators honor this flag by omitting readOnly fields from create and update request types.

The deprecated: true flag marks operations and schemas as deprecated without removing them. Swagger UI and Redoc render deprecated operations with a strikethrough style. Code generation tools may annotate generated methods with language-specific deprecation annotations. Marking an endpoint as deprecated in the spec is the correct way to signal to API consumers that they should migrate, without breaking existing integrations immediately.

Example objects in schemas help both documentation and contract testing. A schema property can include an example value that Swagger UI and Redoc display in the documentation. The examples field in a request or response content object allows multiple named examples. Mock server tools like Prism use these examples to generate realistic mock responses.

When using external dollar-refs that point to separate files, the path must be resolvable at build time. $ref: "./schemas/user.yaml#/User" works when user.yaml is in the same directory. The swagger-cli bundle command resolves all external references into a single inline file, which simplifies distribution and tool compatibility. Code generation tools often require a single-file spec or a bundled spec rather than a multi-file spec.

Omitting operationId from operations is the most impactful mistake for code generation. Without operationId, generators invent names based on the HTTP method and path. GET /v1/users/orders/items becomes something like getV1UsersOrdersItems, which is verbose and unpredictable. Adding operationId: listOrderItems gives generators a clean, intentional name that appears in the generated SDK.

Missing the required array in object schemas makes all properties optional in generated TypeScript interfaces and Python dataclasses. A User with required: [id, name, email] generates TypeScript as { id: number; name: string; email: string }. Without the required array, it generates as { id?: number; name?: string; email?: string }, which requires callers to handle undefined for fields that the API guarantees are always present.

Using string response descriptions without content schemas tells code generators nothing about the response shape. The responses field in an operation should always include a content key with an application/json media type and a schema. Without it, code generators produce response types of void or any, making the SDK useless for type-safe consumption.

Defining a security scheme without applying it is a common oversight. The scheme definition in components/securitySchemes only registers the authentication method. Adding the global security field or per-operation security fields is what actually tells clients and code generators to include the Authorization header.

Forgetting to validate the spec before publishing means errors accumulate and become harder to fix. Each breaking fix to the spec after external clients have generated code from it requires those clients to regenerate. A validation step in CI, running swagger-cli validate and spectral lint on every pull request, catches errors before they reach external consumers.

Spec-first development inverts the typical workflow. Instead of writing server code and then documenting it, you write the OpenAPI spec first, validate it, and then use the spec to generate both server stubs and client SDKs. This approach guarantees that the spec is always accurate because the server is implemented against it by construction.

Keeep the spec in version control alongside the server code. When a developer changes an endpoint, they must also update the spec as part of the same pull request. A CI check that validates the spec prevents the spec from drifting from the implementation. Some teams run spectral lint as a required check so that design rule violations block merge.

Use the servers array to document multiple environments. Add a servers entry for production, staging, and local development. Swagger UI and Redoc display a server selector that lets developers switch between environments when testing from the documentation. This eliminates the need for separate documentation per environment.

Generate human-readable documentation automatically from the spec. Redoc produces clean, three-panel documentation with navigation, schema descriptions, and request examples. Swagger UI provides an interactive sandbox where developers can make real API calls from the browser. Both tools take the spec file as input and render without any custom templates.

For TypeScript projects, ts-node-codegen and openapi-typescript generate type-safe interfaces directly from the spec. These interfaces can be imported by both the server and client, ensuring they use the same type definitions. When the spec changes, regenerating the types surfaces breaking changes at compile time rather than at runtime.

Test endpoints with /tools/http-request-builder to verify that actual server behavior matches the spec. Spec validation checks the document structure but cannot verify that the server produces the documented response shapes. Regular manual spot-checks or automated contract tests using a tool like Dredd close this gap.