OpenAPI

The OpenAPI Specification is a standard format for describing an HTTP API so that tools, not just people, can read it. One document lists every path and method, the parameters each takes, the request and response bodies as JSON Schema, the status codes and the authentication schemes. Swagger was its original name; OpenAPI 3.1 is the current major version.

How it works

From one document, tools generate interactive reference docs, client SDKs in many languages, server stubs, mock servers and contract tests. The same file can be checked in CI against the running API, so the description and the implementation cannot drift apart without a build failing.

The misconception

That an OpenAPI file proves the API behaves as described. It is a claim, not a test: nothing stops a handler from returning a field the spec never mentions or a status it never lists. Its value comes from being checked against real responses, which is what contract testing does.

Try it here

Every API here publishes its own OpenAPI 3.1 document at /docs/{api-id}/openapi.json, and /openapi.json covers the whole catalog; both are generated from the same definitions the docs pages render.

Related

• Contract testing
• JSON Schema

Other terms

• Mock API — A stand-in for a real API that returns realistic responses without the real system behind it.
• REST API — An API that models a system as addressable resources, manipulated with standard HTTP methods.
• ETag — An opaque version identifier for a representation, used to avoid re-sending it and to detect conflicting writes.
• HATEOAS — Hypermedia as the Engine of Application State — responses carry the links to whatever you can do next.
• Bearer token — A credential where possession alone grants access — whoever holds it can use it.
• JWT (JSON Web Token) — A signed, self-contained token whose payload the server can verify without a database lookup.

All glossary terms · Testing techniques · All 39 mock REST APIs

Last updated 2 October 2026