The OpenAPI Specification Explained

The OpenAPI Specification is the ultimate source of knowledge regarding this API description format. However, its length is daunting to newcomers and makes it hard for experienced users to find specific bits of information. This chapter provides a soft landing for readers not yet familiar with OpenAPI and is organized by topic, simplifying browsing.

The following pages introduce the syntax and structure of an OpenAPI Description (OAD), its main building blocks and a minimal API description. Afterwards, the different blocks are detailed, starting from the most common and progressing towards advanced ones.

• Structure of an OpenAPI Description: JSON, YAML, openapi and info
• API Endpoints: paths and responses.
• Content of Message Bodies: content and schema.
• Parameters and Payload of an Operation: parameters and requestBody.
• Reusing Descriptions: components and $ref.
• Providing Documentation and Examples: description and example/examples.
• API Servers: servers.