Structure of an OpenAPI Document

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.

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.

त्वरित जाँच: In an OpenAPI document, what does info.version describe?

• The OpenAPI Specification version
• The version of Swagger UI
• The HTTP version
• The version of the API being described