Структура документа

Корневой объект OpenAPI

Поле	Тип	Описание
openapi	строка	Обязательное. Версия спецификации, например 3.0.3. Это не версия вашего API — её указывают в info.version.
info	объект Info	Обязательное. Сведения об API.
servers	массив Server	Серверы, на которых доступен API. Если не заданы — считается один сервер с адресом /.
paths	объект Paths	Обязательное. Пути и операции.
components	объект Components	Переиспользуемые схемы, параметры, ответы и т. д.
security	массив Security Requirement	Схемы безопасности, действующие для всех операций по умолчанию.
tags	массив Tag	Теги для группировки операций с описаниями.
externalDocs	объект External Documentation	Ссылка на внешнюю документацию.

Info — сведения об API

Поле	Описание
title	Обязательное. Название API.
version	Обязательное. Версия документа (вашего API), например 1.4.0.
description	Описание, поддерживает CommonMark.
termsOfService	Ссылка на условия использования.
contact	Контакт: name, url, email.
license	Лицензия: name (обязательное), url.

info:
  title: API интернет-магазина
  version: 2.1.0
  description: |
    API для каталога, корзины и заказов.
  termsOfService: https://example.ru/terms
  contact:
    name: Команда API
    url: https://example.ru/support
    email: api@example.ru
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html

Server — сервер

Поле	Описание
url	Обязательное. Адрес сервера; может быть относительным и содержать переменные в фигурных скобках.
description	Описание, например «Тестовый контур».
variables	Переменные для подстановки в url.

Переменная сервера (Server Variable) имеет поля default (обязательное — значение по умолчанию), enum (допустимые значения) и description.

servers:
  - url: https://api.example.ru/v1
    description: Продуктив
  - url: https://{stand}.example.ru/v1
    description: Тестовые стенды
    variables:
      stand:
        default: test
        enum: [test, preprod]

Серверы можно задать и на уровне пути или операции — тогда они заменяют серверы из корня для этой части API.

Полный пример структуры

openapi: 3.0.3
info:
  title: API библиотеки
  version: 1.0.0
  description: Каталог книг и выдача читателям.
servers:
  - url: https://library.example.ru/api/v1
tags:
  - name: Книги
    description: Каталог книг
paths:
  /books:
    get:
      tags: [Книги]
      summary: Список книг
      operationId: listBooks
      responses:
        '200':
          description: Книги
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Book'
components:
  schemas:
    Book:
      type: object
      required: [id, title]
      properties:
        id:
          type: integer
          format: int64
        title:
          type: string
        author:
          type: string
externalDocs:
  description: Руководство разработчика
  url: https://library.example.ru/docs