An OpenAPI description turns parts of an HTTP API contract into data that software can inspect (OpenAPI Initiative, sec. 2). That is its practical value. It replaces some guesswork about paths, operations, inputs, outputs, and security declarations with fields that can be parsed and compared (OpenAPI Initiative, secs. 4.8-4.10, 4.27). It does not turn the declaration into runtime truth, grant permission to call the service, or decide whether an automated action is appropriate.
Finding an openapi.json file is only the first check. The published description also needs to be detailed, current, and clearly connected to the API it claims to describe.
What the document actually describes
The OpenAPI Specification defines a programming-language-neutral interface description for HTTP APIs. Its stated purpose is to let people and computers understand a service's capabilities without source-code access or traffic inspection (OpenAPI Initiative, sec. 2). A conforming OpenAPI document is a JSON object represented as JSON or YAML, and it identifies the specification version used to interpret its fields (OpenAPI Initiative, secs. 3, 4.1.1).
The structure moves from the API down to individual operations. A servers array can identify base URLs. A paths object holds relative endpoint paths, a Path Item associates HTTP methods with those paths, and an Operation Object can describe parameters, a request body, possible responses, deprecation, and operation-level security requirements (OpenAPI Initiative, secs. 4.5, 4.8-4.10). Reusable schemas, parameters, responses, and security schemes can live under components (OpenAPI Initiative, sec. 4.7).
Those fields make a declared contract inspectable. A reviewer can ask whether an operation has a stable identifier, whether path parameters are defined, whether error responses have schemas, and whether a deprecated operation is marked as such. Software can perform the same structural checks without trying to infer an interface from prose.
Parseable is not the same as complete
OpenAPI permits descriptions with limited visible detail. In version 3.2.0, the root must include at least one of components, paths, or webhooks, but a paths object may be empty because access controls can limit what a viewer sees (OpenAPI Initiative, secs. 4.1.1, 4.8). Many descriptive fields, including operation summaries and descriptions, are optional (OpenAPI Initiative, secs. 4.9.1, 4.10.1). A file can therefore satisfy basic structural requirements while remaining difficult to use.
Accuracy is a separate question. The document reports what the publisher declares. It does not execute an operation, observe a production response, or compare the service with the schema. A securitySchemes entry describes an available mechanism, while a Security Requirement Object declares which schemes an operation requires; neither object supplies credentials or grants authorization (OpenAPI Initiative, secs. 4.27, 4.30).
Here the description stops and runtime behavior begins. A detailed document can reduce ambiguity for documentation tools, client developers, and other supporting software. It cannot ensure that a caller chooses the right operation, provides valid real-world values, handles side effects, or follows the service's policies.
Description and discovery are different jobs
The specification recommends naming an entry document openapi.json or openapi.yaml, but that is a naming recommendation rather than a universal root URL (OpenAPI Initiative, sec. 4.1.2). A publisher still needs to link the description from documentation or expose a separate discovery mechanism.
RFC 9727's API catalog is one such mechanism. It defines /.well-known/api-catalog and recommends that catalog entries include links to OpenAPI descriptions where relevant (Smith, secs. 2, 4.1). The catalog answers "where is the description?" OpenAPI answers "what interface is being declared?" Keeping those roles separate makes both files easier to maintain.
For publishers, a sound workflow is straightforward. Generate what can be derived from code, then review the public result. Add operation summaries that distinguish similar actions, document required inputs, include realistic non-secret examples, describe expected error responses, mark deprecated elements, and remove internal-only routes. Validate the document against the OAS version it declares, and update it in the same release process as the API.
What this check can and cannot establish
When API or protocol checks are selected, MachineRead requests /openapi.json, /api/openapi.json, and /swagger.json. It records an API-description candidate when a successful response contains at least 20 characters after trimming whitespace and parses as a JSON object or array. Although OpenAPI permits YAML, this probe looks for JSON at those three paths and does not count a YAML-only description. This is a reachability and parseability signal from the audited origin under the audit's request conditions.
The check does not validate the response against an OpenAPI schema, follow every reference, grade documentation quality, or compare declared operations with live behavior. It does not call the listed operations, test credentials or authorization, assess side effects, certify API security, or determine whether any particular client can use the description correctly. A missing signal also does not prove that no description exists; it may be published at a location outside the paths the audit checks.
Works Cited
OpenAPI Initiative. "OpenAPI Specification v3.2.0." OpenAPI Initiative, Linux Foundation, 19 Sept. 2025, https://spec.openapis.org/oas/v3.2.0.html. Accessed 7 Aug. 2026.
Smith, Kevin. "api-catalog: A Well-Known URI and Link Relation to Help Discovery of APIs." RFC 9727, Internet Engineering Task Force, June 2025, RFC Editor, https://www.rfc-editor.org/rfc/rfc9727.html. Accessed 7 Aug. 2026.
See also
- Methodology reference - documents the openapi.json probe and the machine_surfaces check group
- Launch post - explains the audit's evidence boundaries
- Related: api-catalog.json and ai-catalog.json