OpenAPI

It is a JSON Pointer into the same document: it resolves to the Pet entry under components.schemas, and tooling substitutes that definition wherever the reference appears, so one definition can serve many operations.

In an OpenAPI schema, required is an array of property names declared on the object schema itself, not a boolean on each property. It only guarantees the key is present — a required property can still hold null if the schema allows null.

In an OpenAPI schema, type is the JSON data type — string, number, integer, boolean, array, object — and is enforced by validators. format is an open-ended hint refining that type, such as int64 or date-time; validators may ignore unknown formats, but code generators use them for type mapping.

Security schemes live under components.securitySchemes as named entries. OpenAPI 3.0 defines four types — apiKey, http, oauth2 and openIdConnect — and 3.1 adds mutualTLS. Operations then reference a scheme by its name in a security requirement.

An OpenAPI 3.x document is one object whose root keys are openapi, info, servers, paths, components, security, tags and externalDocs. Only openapi and info are always required; 3.0 also requires paths, and 3.1 adds webhooks and jsonSchemaDialect.

Contract-first treats the hand-written OpenAPI document as the source of truth and derives code from it; code-first treats the implementation as the truth and generates the document from annotations. The first buys design review and parallel work, the second buys speed and automatic freshness.

Both derive models from the spec's schemas, but a server generator emits routing or controller interfaces you implement, while a client generator emits a ready-to-call HTTP client. The generator is chosen with -g, and operationId and tags determine method and class names.

In OpenAPI 3.x anything sent in the HTTP message body is a requestBody, never a parameter. Its content map is keyed by media type, each entry carrying its own schema and examples. requestBody defaults to required: false, so a mandatory payload must say so explicitly.

OpenAPI's style picks the serialization rule and explode says whether each array item gets its own key. Query parameters default to style: form with explode: true, giving tags=a&tags=b; explode: false gives tags=a,b. spaceDelimited and pipeDelimited use spaces or pipes instead.

In an OpenAPI schema, allOf requires the value to satisfy every subschema, anyOf requires at least one, and oneOf requires exactly one. allOf is used for composition, oneOf for alternatives, and anyOf for overlapping permissive unions.

OpenAPI 3.0 uses its own keyword, nullable: true, alongside a single type. OpenAPI 3.1 removed nullable and follows JSON Schema 2020-12, where you write a type array such as type: [string, "null"].

A root-level OpenAPI security block is the default for every operation. An operation's own security field replaces that default entirely rather than adding to it, and an empty array removes the inherited requirement, making the operation public.

An OpenAPI operation object describes one HTTP method on one path: tags, summary, description, operationId, parameters, requestBody, responses, callbacks, deprecated, security and servers. operationId is a document-unique name that tooling uses to identify the operation, typically as the generated method name.

Both render the same OpenAPI document as HTML. Swagger UI is an interactive explorer whose Try it out sends real requests from the browser; Redoc is a read-only three-panel reference page. The choice is interactivity versus a clean published reference.

OpenAPI's components object also holds responses, parameters, examples, requestBodies, headers, securitySchemes, links and callbacks — plus pathItems in 3.1. Each is reused with a $ref at a position where that object type is allowed; security schemes are the exception, referenced by key name.

Relative file references resolve against the base URI of the document containing the reference, not the root spec, and may carry a fragment pointer into the target. URL references fetch at build time. Split specs commonly break because tools resolve differently, so bundle before publishing.

Two schemes inside one OpenAPI security requirement object mean AND — the caller must satisfy both. Two requirement objects in the security array are alternatives, meaning OR — satisfying any one of them authorizes the request.

OpenAPI's http scheme field names an HTTP authentication scheme from the IANA registry — basic, bearer, digest — and determines the Authorization header's form. bearerFormat is a free-text documentation hint about the token's format and is ignored by tooling.

An OpenAPI responses object maps quoted HTTP status codes such as '200', uppercase range wildcards such as '4XX', and the literal key default to Response Objects. default covers any status not matched explicitly. Every Response Object requires a description.

OpenAPI 3.0 replaced Swagger 2.0's host, basePath and schemes with a servers array, turned body and formData parameters into requestBody, replaced document-level consumes and produces with per-operation content maps, and moved definitions, parameters, responses and securityDefinitions under components.

Generate into a build output directory, never hand-edit the result, pin the generator version so output does not shift under you, and wrap generated clients behind your own interface. Then decide deliberately whether to commit the output or regenerate it every build.

Publish one shared Spectral ruleset that each repository extends, define rules as a JSONPath given plus a then function and severity, run spectral lint in CI, and gate the build with --fail-severity. Introduce new rules at warn before promoting them to error.

Declare a requestBody with a multipart/form-data content entry whose schema is an object: each property becomes one part. The encoding map then overrides a part's Content-Type and adds part headers, since OpenAPI otherwise infers the part type from the property's schema.

OpenAPI offers three ways: style form with explode true, which flattens the object into top-level keys; style deepObject, which produces bracketed keys like filter[status]=open; and a content-typed parameter carrying the value as JSON. deepObject fails for nested objects and arrays.

Yes — recursive references are legal and normal for tree-shaped data, provided the cycle passes through an optional or array property so an instance can terminate. Cycles through required properties describe unsatisfiable data, and any tool that inlines references instead of keeping them recurses forever.

In an OpenAPI schema, additionalProperties controls properties not listed under properties: true (the default) allows any, false rejects them, and a schema value types them, which is how free-form maps are modelled. Setting false breaks allOf composition and blocks additive evolution.

An OpenAPI discriminator names a property whose value tells tooling which subschema a polymorphic payload belongs to. It requires propertyName, that property must be present and required in every variant, and it is a serialization hint — it does not replace oneOf validation.

An OpenAPI oauth2 scheme's flows object names which grant types the API supports — authorizationCode, clientCredentials, password, implicit — each with its endpoint URLs and a required scopes map of scope name to description. Operations then reference subsets of those scope names.

OpenAPI 3.1 adds the root keys webhooks and jsonSchemaDialect, makes paths optional so a document may describe only webhooks or components, adds a pathItems bucket to components, adds info.summary and an SPDX license.identifier, and aligns Schema Objects with JSON Schema 2020-12.