What is the OpenAPI spec?

In a nutshell

The OpenAPI specification is a human and machine-readable specification used to create JSON or YAML documents that describe HTTP APIs.

Describing an API in a standard format unlocks several capabilities:

• You can use the spec document to generate interactive documentation (e.g., using a tool like Swagger UI).
• Developers can read the spec to understand how to use the API (e.g., what endpoints are available, what data is expected for each endpoint, what status code is returned, etc.).
• You can generate server stubs and client SDKs from spec (e.g., using a tool like Swagger CodeGen).

The spec schema

The full schema reference can be found here, but what follows are some of the most important fields.

openapi

Specifies the version number of the spec (e.g., 3.0.1).

info

Provides metadata about the API. For example:

"info": {
  "title": "My Lovely API",
  "description": "Some description",
  "version": "0.0.0"
},

paths

Describes the paths and operations (e.g., GET, POST) for the API. Each operation (e.g., POST /clients) will have the following fields

• operationId
• tags
• responses
• requestBody – can contain references to other OpenAPI components (see below).
• parameters
• <your-custom-fields>

servers

An array of Server Objects, which provide connectivity information to the API’s consumers.

components

Contains a set of reusable objects that can be referenced within the document

Field Name	Type	Description
schemas	Map[string, Schema Object]	An object to hold reusable Schema Objects that can be used to describe request bodies or responses. This object is a superset of the JSON Schema Specification Draft 2020-12.
responses	Map[string, Response Object | Reference Object]	An object to hold reusable Response Objects.
parameters	Map[string, Parameter Object | Reference Object]	An object to hold reusable Parameter Objects.
examples	Map[string, Example Object | Reference Object]	An object to hold reusable Example Objects.
requestBodies	Map[string, Request Body Object | Reference Object]	An object to hold reusable Request Body Objects.
headers	Map[string, Header Object | Reference Object]	An object to hold reusable Header Objects.
securitySchemes	Map[string, Security Scheme Object | Reference Object]	An object to hold reusable Security Scheme Objects.
links	Map[string, Link Object | Reference Object]	An object to hold reusable Link Objects.
callbacks	Map[string, Callback Object | Reference Object]	An object to hold reusable Callback Objects.
pathItems	Map[string, Path Item Object | Reference Object]	An object to hold reusable Path Item Object.

Sources

• OpenAPI-Specification – GitHub
• OpenAPI specification – Wikipedia
• Schema
• Example specs