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. The different blocks are then 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.
• HTTP Methods: standard and custom HTTP methods.
• 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: summary, description and example/examples.
• API Servers: servers.
• Describing API Security: securitySchemes and security.
• Enhanced Tags: tags.
• Providing Callbacks: callbacks.
• Providing Webhooks: webhooks.
• Implementing Links: links.
• Sequential Media Types: itemSchema and streaming media types.