Understanding the basic structure of OAS

The OpenAPI definition structure can be divided into the following sections (all are keywords and case-sensitive):

• openapi (version)
• info
• externalDocs
• servers
• tags
• paths
• components

All the preceding terms are part of root. The first three sections (openapi, info, and externalDocs) are used to define the metadata of the API.

You can place an API’s definition either in a single file or divided into multiple files. OAS supports both. We’ll use a single file to define the sample e-commerce API.

Instead of discussing all the sections theoretically and then writing the e-commerce API definitions, we’ll do both together. First, we’ll cover each section definition of the e-commerce API, and then we’ll discuss why we have used it and what it implies.

The metadata sections of OAS

Let’s have a look at the metadata sections of the e-commerce API definitions:

...