What this check tests
The audit requests 15 fixed paths on your origin in parallel: /openapi.json, /swagger.json, /.well-known/openapi, /api-docs, /api/docs, /v3/api-docs, /v2/api-docs, /swagger/v1/swagger.json, /swagger/doc.json, /api/v3/openapi.json, /api/openapi.json, /api/swagger.json, /spec.json, /api-docs.json and /docs/openapi.json. A response counts when it is 200, parses as JSON, and has an openapi or swagger key.
Two fallbacks run only if none of the 15 matched:
- If a path returned a Swagger UI page (its HTML mentions
swagger-uiorSwaggerUIBundle), the audit follows theurlsetting in it. - It then tries same-origin homepage links whose address contains
openapi,swagger,api-docs,api/docsorspec.json.
A document is accepted only if it has a paths object. The audit counts operations (get, post, put, patch, delete, head, options) under each path, up to 200. A document whose first servers entry is an absolute URL on another origin is rejected.
- Pass 100: at least one operation.
- Partial 50: a document with
pathsbut no operations. - Fail 0: nothing found.
- Skip: replaces a fail when the public API check failed or was skipped. A pass or partial is kept regardless.
Two gaps to know about. The audit only parses JSON, so an openapi.yaml is not found. And OpenAPI 3.1 and later allow a document with only components or webhooks; the audit would not find it.
Why it matters to agents
The OpenAPI Specification describes an HTTP API in a form that lets "both humans and computers" discover and understand it without source code or traffic inspection. For an agent that is the difference between guessing endpoints and reading a list of operations, parameters and request bodies. The specification recommends naming the entry document openapi.json or openapi.yaml.
This is useful for agent tooling that turns an API description into callable tools, so the payoff is concrete only if you want agents to call your API. If you have no API there is nothing to describe, and the check is skipped.
How to fix it
- Generate the document from your framework or API gateway rather than writing it by hand, and serve it as JSON at
https://example.com/openapi.json(any of the 15 paths works). - Keep
pathspopulated with real operations. Give each anoperationIdand a one-linesummaryso a tool can name and choose it. - The audit discards a document whose absolute
serversURL is on another host. Aserversentry names the host that actually serves the API, so do not point it at an origin that does not. Either serve or proxy the API on the audited origin for real, or, if the API lives on its own host, accept that this check describes the site that hosts the API and audit that host. - If you only have YAML today, also publish the JSON form. Many generators output both.
- Declare how callers authenticate in the document's security schemes, and see OAuth discovery for the matching server-side metadata.
A minimal valid document:
{
"openapi": "3.1.0",
"info": { "title": "Example API", "version": "1.0.0" },
"paths": {
"/projects": {
"get": { "operationId": "listProjects", "summary": "List projects" }
}
}
}
List it in an API catalog so tools can find it from /.well-known/api-catalog, as RFC 9727 describes.