# Structure of an OpenAPI Document — OpenAPI / Swagger

Source: https://www.skillbyai.com/en/openapi/f-structure

> Name the top-level sections of an OpenAPI 3.1 document and their purpose.

## The top-level map

An OpenAPI 3.1 document has a small set of top-level fields. **`openapi`**: the specification version (`3.1.0`). **`info`**: title, version of **your API** (not of the spec), description (Markdown is allowed), contact, licence and terms of service. **`servers`**: base URLs, possibly with **variables** (`https://{region}.api.example.com`). **`paths`**: the endpoints, each with **operations** for HTTP methods. **`webhooks`** (new in 3.1): requests your API sends to clients. **`components`**: reusable definitions referenced elsewhere with **`$ref`**: `schemas`, `responses`, `parameters`, `examples`, `requestBodies`, `headers`, `securitySchemes`, `links`, `callbacks` and `pathItems`. **`security`**: default security requirements for all operations. **`tags`**: groups with descriptions for documentation. **`externalDocs`**: links to further documentation. In 3.1 a document needs at least one of `paths`, `webhooks` or `components`, so a document can contain only shared components. Large APIs split the description across several files joined by `$ref`, then **bundle** them for publishing.

## Top-level fields in context

A skeleton showing where each part lives.

```yaml
openapi: 3.1.0
info:
  title: Orders API
  version: 2.3.0                     # version of THIS API
  contact: { name: Platform team, email: api@example.com }
  license: { name: Apache-2.0, identifier: Apache-2.0 }
servers:
  - url: https://{region}.api.example.com/v2
    variables:
      region: { default: in, enum: [in, eu, us] }
tags:
  - name: Orders
    description: Create and track orders
security:
  - bearerAuth: []                  # applies to every operation unless overridden
paths:
  /orders:
    get:  { $ref: './paths/orders-list.yaml' }
    post: { $ref: './paths/orders-create.yaml' }
webhooks:
  orderShipped: { $ref: './webhooks/order-shipped.yaml' }
components:
  schemas:
    Order: { $ref: './schemas/order.yaml' }
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT }
```

## A building plan with an index

`info` is the cover page, `servers` is the address, `paths` are the floor plans of each room, and `components` is the appendix of standard fittings that every floor plan refers to instead of redrawing them.

**Quiz:** In an OpenAPI document, what does info.version describe?

- [ ] The OpenAPI Specification version
- [ ] The version of Swagger UI
- [ ] The HTTP version
- [x] The version of the API being described

*Answer:* The version of the API being described. The spec version goes in the top-level openapi field; info.version is your API's own version.