Protocols
Saved & recent

OpenAPI

Also called: OAS, OpenAPI description, Swagger specification

OpenAPI is a standard format for describing HTTP APIs in a machine-readable document. It can specify paths, operations, parameters, request bodies, response schemas and security requirements. Documentation tools, client generators and validators can use that description; OpenAPI itself is not the protocol that carries an API call.

A hypothetical document can describe GET /books/{id} as accepting an integer identifier and returning a Book representation or a 404 response. The running server must still implement that contract. A valid description does not prove that the server obeys it, and the OpenAPI document’s specification version is distinct from the API’s product version.

Read first
HTTP
Related
HTTP, API versioning, REST, WSDL
Further reading
OpenAPI Initiative — OpenAPI Specification 3.1.1
OpenAPI description OAS format version API version generated docs client code contract checks actual HTTP request actual HTTP response client implementation compare behavior
An OpenAPI description can drive documentation, client generation, and contract checks. Actual calls still travel over HTTP to an implemented server; the format’s specification version is separate from the API’s product version.

View in the full Protocols collection