The OpenAPI Specification provides a formal standard for describing HTTP APIs, describing the surface area of request and response APIs. OpenAPI can be used to publish documentation, generate mock servers, and produce SDKs. An OpenAPI has become an expected artifact by API consumers and is widely considered to act as the technical contract between API produce and consumer and has become common for many leading API providers.

Also known as: OAS, OpenAPI Specification, Swagger (historical, pre-3.0)

Standards

• OpenAPI Initiative (Linux Foundation) OpenAPI Specification 3.1.0
• OpenAPI Initiative (Linux Foundation) OpenAPI Specification 3.0.4
• OpenAPI Initiative (Linux Foundation) Arazzo Specification 1.0.1
• OpenAPI Initiative (Linux Foundation) Overlay Specification 1.0
• IETF (JSON Schema WG) JSON Schema Draft 2020-12 (aligned by OAS 3.1)
• IETF RFC 9727 — api-catalog Well-Known URI
• IETF RFC 8615 — Well-Known URIs

Well-Known Paths

• /.well-known/api-catalog — RFC 9727 — Linkset advertising API descriptions; entries typically use the service-desc relation.
• /openapi.json — Convention (not IANA-registered) — De facto path for an OpenAPI JSON document at the API root.
• /openapi.yaml — Convention (not IANA-registered) — De facto path for an OpenAPI YAML document at the API root.

Media Types

• application/vnd.oai.openapi — IANA-registered for OpenAPI in YAML.
• application/vnd.oai.openapi+json — IANA-registered for OpenAPI in JSON.
• application/json — Common transport for OAS documents in JSON.
• application/yaml — Common transport for OAS documents in YAML.

OpenAPI Expression

• openapi (OpenAPI 3.x) — Version string at the root of every document (e.g. "3.1.0").
• info (OpenAPI 3.x) — API metadata — title, version, license, contact, summary.
• servers (OpenAPI 3.x)
• paths (OpenAPI 3.x)
• webhooks (OpenAPI 3.1) — Top-level map of incoming webhook operations (new in 3.1).
• components (OpenAPI 3.x)
• tags (OpenAPI 3.x)

Link Relations

• service-desc — RFC 8631 — Points to a machine-readable API description (commonly an OpenAPI document).
• service-doc — RFC 8631 — Points to human-readable API documentation generated from OpenAPI.
• describedby — RFC 8288 — Used to associate a resource with its schema.

Governance Rules

• oas3-schema (Spectral built-in) — Document must validate against the OpenAPI 3.x JSON Schema.
• operation-operationId (Spectral built-in) — Every operation should have a unique operationId.
• operation-tags (Spectral built-in) — Operations should be tagged for discoverability.
• info-contact (Spectral built-in) — Info object should include a contact.
• oas-tag-description (Spectral built-in) — Each tag should carry a description.
• no-$ref-siblings (Spectral built-in) — Siblings of $ref are ignored in OAS 3.0 — flag them.

Risk & Compliance

OWASP:

• OWASP API Security Top 10: API9:2023 Improper Inventory Management — outdated or undocumented OAS leads to shadow/zombie endpoints
• OWASP API Security Top 10: API8:2023 Security Misconfiguration — OAS without security requirements masks unauthenticated endpoints

Compliance:

• SOC 2 CC8.1 — change management requires accurate API inventory
• PCI DSS v4 Req. 6.2 — documented system components and interfaces

Security: An incomplete or stale OpenAPI hides attack surface. Publish OAS as part of CI, validate that every deployed route is described, and never expose servers pointing at internal hosts. Treat the OAS itself as build-time governance input for gateways and WAFs.

Tools

• Swagger Editor / UI — Editor / Renderer (Apache-2.0)
• Redocly CLI — Linter / Renderer (MIT)
• Spectral — Linter (Apache-2.0)
• openapi-generator — Codegen (Apache-2.0)
• Prism — Mock server (Apache-2.0)
• Optic — Diff / governance

Suggested Metrics

• oas_coverage — Share of production endpoints described in an OpenAPI document.
• oas_lint_violations — Count of governance-rule violations across the document.
• oas_breaking_changes — Count of breaking changes detected between versions (e.g. via openapi-diff).
• oas_freshness_days — Days since the OpenAPI document was last regenerated or published.

Example Implementations

• Stripe — Publishes an OpenAPI document at github.com/stripe/openapi.
• GitHub — Publishes the REST API description at github.com/github/rest-api-description.
• Twilio — Publishes per-product OAS at github.com/twilio/twilio-oai.
• DigitalOcean — Publishes OAS at github.com/digitalocean/openapi.

Related Properties

• Asyncapi
• Json schema
• Webhooks
• Openapi plugin manifest
• Postman collection

Tags

• Machine-Readable
• APIs

All Community Properties