OpenAPI specification: what the check tests and how to fix it

Weight 2. Looks for a JSON OpenAPI or Swagger document with a paths object and one operation at 15 common paths. YAML is not detected. Skipped if no API.

Agent Auth · Weight 2 in the w2agent Score

How common is it?

9% of 378 measured sites where this check applied pass.

Latest audit of each site under rubric v3.1. Sites where the check did not apply or could not be measured (for example, no llms.txt for the llms.txt checks) are left out. A partial result does not count as a pass.

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-ui or SwaggerUIBundle), the audit follows the url setting in it.
  • It then tries same-origin homepage links whose address contains openapi, swagger, api-docs, api/docs or spec.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 paths but 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 paths populated with real operations. Give each an operationId and a one-line summary so a tool can name and choose it.
  • The audit discards a document whose absolute servers URL is on another host. A servers entry 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.

Examples from measured sites

Up to 10 of the highest-scoring sites in each group, from recent audits. Failing includes partial results.

Passing

Failing or partial

Sources

Verified against these sources on

Does your site pass this check?

Check your own site →