openapi-discovery 1.0.0

OpenAPI Discovery Check v1.0.0

Status

• Version: 1.0.0
• Check identifier: openapi-discovery
• Input contract: [email protected]
• Output contract: [email protected]
• Scope: site-level public API description discovery
• Maturity: established

Abstract

This check validates whether an origin that publishes or claims a public API exposes a usable OpenAPI or Swagger description. It looks for OpenAPI/Swagger documents at common same-origin locations, validates the baseline document shape, and records whether the document contains enough operation detail for machine clients and agents.

OpenAPI discovery is different from API catalog discovery. API catalogs and Link headers help clients find service descriptions; this check validates the OpenAPI or Swagger document itself when one is expected or discovered.

Motivation

API-consuming agents need a machine-readable contract before they can safely choose operations, construct requests, interpret responses, and understand authentication. Human documentation and interactive API explorers are helpful, but they are weaker evidence than a valid OpenAPI or Swagger document.

Many public APIs expose OpenAPI through conventional paths or developer portal configuration instead of a single standard well-known URL. A useful check must therefore combine standards-aware validation with pragmatic discovery.

Normative Model

This version follows:

• The OpenAPI Specification for OpenAPI 3.x documents.
• The Swagger 2.0 Specification for legacy Swagger documents.
• RFC 8288 for web linking semantics where OpenAPI documents are advertised.
• RFC 8631 for the service-desc relation, which can identify

machine-readable service descriptions.

• RFC 9727 for API Catalog discovery where catalogs point to OpenAPI

descriptions.

Normative expectations used by the check:

• OpenAPI 3.x documents use a root openapi version field.
• Swagger 2.0 documents use a root swagger version field.
• The root document must be an object.
• The document must include API metadata in info.
• API operations must be discoverable through paths and, for newer OpenAPI

versions, may also be represented through webhooks.

• Operations need responses to be machine usable.
• OpenAPI 3.x server information belongs in servers.
• Swagger 2.0 location information belongs in host, basePath, and

schemes.

• Authentication should be declared through security schemes or explicitly left

unauthenticated when appropriate.

• Specification extensions using x- fields are allowed but are not a

substitute for required OpenAPI/Swagger fields.

Applicability

The check applies when public evidence suggests the origin publishes APIs or claims OpenAPI/Swagger support:

• A conventional OpenAPI or Swagger candidate path returns HTTP 2xx.
• Homepage headers or HTML advertise a service description.
• API catalog or Link header evidence points to an OpenAPI or Swagger document.
• Homepage or developer content mentions OpenAPI, Swagger, REST API, API

reference, developer docs, SDKs, or public endpoints.

The check is not applicable when:

• No OpenAPI/Swagger candidate exists.
• The homepage and response headers contain no public API/developer signals.
• The site exposes only ordinary website pages, browser forms, private app

routes, or account-only functionality.

Pass Criteria

The check passes when:

• A same-origin OpenAPI or Swagger candidate is discovered.
• The candidate is fetched successfully over HTTPS.
• The response body parses as JSON or YAML.
• The root document is an object.
• The version field is OpenAPI 3.x or Swagger 2.0.
• Required info metadata is present.
• Usable paths, operations, or webhooks are present.
• Operations include response definitions.
• The document provides enough machine-usable detail for agents, including

parameters or request bodies, response schemas or media types, server information, and security schemes or explicit no-auth evidence where applicable.

Warning Criteria

Warnings include:

• public API or developer signals are visible but no OpenAPI or Swagger document is found
• a valid OpenAPI/Swagger document is found but lacks enough schemas, parameters, request bodies, response media types, server details, or security declarations for reliable agent use
• the document is reachable only through weaker discovery hints such as conventional paths without explicit links
• optional metadata such as contact, license, terms, tags, operation IDs, examples, or auth detail is incomplete
• compatible but generic content types are used
• external servers, references, or docs introduce additional trust boundaries

Failure Criteria

Failures include:

• the site claims a public API/OpenAPI/Swagger surface but no same-origin candidate is fetchable
• the selected candidate is not fetched successfully or is not served over HTTPS
• the body cannot be parsed as JSON or YAML
• the root document is not an object
• the version field is missing or not OpenAPI 3.x / Swagger 2.0
• required info metadata is missing
• no usable paths, operations, or webhooks are present
• operations lack response definitions
• the document exposes credential-bearing, localhost, private-network, internal, or admin-looking URLs

Evidence Model

The check emits step-level evidence:

• Applicability signals from headers, HTML, and candidate paths.
• Candidate URLs, status codes, content types, and fetch errors.
• Selected document URL and discovery source.
• Parsed format: JSON or YAML.
• Version family: OpenAPI 3.x or Swagger 2.0.
• Version string.
• Root-shape diagnostics.
• Path count.
• Operation count by HTTP method.
• Webhook count when applicable.
• Server or host/basePath/schemes evidence.
• Security scheme count and explicit no-auth evidence.
• Request body, parameter, and response schema coverage.
• Machine-usability warnings.
• Security flags for internal URLs, credentials, localhost, private IPs, and

admin-looking paths.

Logs should be emitted through the versioned check runtime wrapper and should include only bounded counts, candidate statuses, selected paths, and sanitized diagnostics. Logs must not include full OpenAPI documents, schemas, examples, credentials, API keys, cookies, tokens, or authorization headers.

Validation/Scoring Steps

The version owns these internal steps:

• applicability (0.10): decide whether the origin publishes or claims a

public API.

• discover-document (0.20): find same-origin OpenAPI/Swagger candidates from

conventional paths, headers, HTML, API catalogs, and UI hints.

• fetch-document (0.15): fetch the best candidate with bounded redirects and

timeouts.

• parse-document (0.15): parse JSON or YAML into an object.
• openapi-shape (0.20): validate version-specific required fields, paths or

webhooks, operations, and responses.

• machine-usability (0.15): check schemas, request bodies, parameters,

servers, authentication, operation IDs, tags, and examples.

• security-review (0.05): flag internal/private/credential-bearing URLs and

unsafe public exposure.

Standard Behavior

If no public API signal is visible and no OpenAPI/Swagger candidate is found, the result is not_applicable.

If public API signals are visible but no valid OpenAPI/Swagger document is found, the result is warning.

If a candidate document exists but is unparsable, malformed, unsupported, or missing required API operation structure, the result is fail.

If a document is valid but weak for automated use, the result is warning. Examples include generic content type, Swagger 2.0 legacy format, missing server information, ambiguous authentication, or operations without useful schemas.

If a document is valid, discoverable, and machine usable, the result is pass.

Non-Standard And Real-World Behavior

OpenAPI itself does not define one universal well-known discovery URI. Real sites commonly expose documents at conventional paths such as:

• /openapi.json
• /openapi.yaml
• /swagger.json
• /swagger.yaml
• /api/openapi.json
• /api/openapi.yaml
• /api/swagger.json
• /api/swagger.yaml
• /docs/openapi.json
• /docs/openapi.yaml
• /api-docs
• /v3/api-docs
• /api/v3/api-docs
• /swagger/v1/swagger.json
• /openapi/v1.json

OpenAPI can also be discovered from Link headers, HTML <link> elements, Swagger UI, Redoc/Redocly, Scalar, API catalogs, APIs.json-style directories, or developer portal configuration.

Common production content types include application/json, application/yaml, application/x-yaml, text/yaml, text/plain, application/octet-stream, application/vnd.oai.openapi+json, and application/vnd.oai.openapi+yaml. Valid documents served with generic content types should be recorded as weaker evidence rather than rejected solely for the content type.

Search engines do not require OpenAPI for rich results or ranking. This check is an API and agent-readiness signal, not a search appearance signal.

Non-Goals And Limitations

This check does not:

• Replace API catalog validation.
• Replace Link header validation.
• Prove that every API operation is callable.
• Authenticate to private developer portals.
• Fetch arbitrary external OpenAPI documents.
• Execute API operations.
• Validate business semantics of schemas or examples.
• Require every website to publish OpenAPI.
• Treat interactive API documentation as a full substitute for a valid

machine-readable description.

References

• spec.openapis.org/oas/latest.html
• spec.openapis.org/oas/v3.2.0.html
• swagger.io/specification/v2
• www.openapis.org/
• www.rfc-editor.org/rfc/rfc8288.html
• www.rfc-editor.org/rfc/rfc8631.html
• www.rfc-editor.org/rfc/rfc9727.html
• www.iana.org/assignments/link-relations/link-relations.xhtml
• www.iana.org/assignments/media-types/media-types.xhtml
• swagger.io/tools/swagger-ui
• redocly.com/docs
• github.com/scalar/scalar
• www.rfc-editor.org/rfc/rfc9264.html
• github.com/APIs-guru/openapi-directory

openapi-discovery v1.0.0 Changelog

Initial versioned package for openapi-discovery.

2026-06-11

• Added deep research-backed versioned documentation covering standards,

applicability, pass/warning/fail boundaries, evidence, limitations, and implementation recommendations.

• Added applicability-aware discovery, expanded conventional paths, Link/HTML

discovery, richer OpenAPI/Swagger validation, machine-usability evidence, and safety review.