Документация / OpenAPI

Введение

Спецификация OpenAPI (OAS) — стандартный, не зависящий от языка программирования способ описать HTTP API: какие есть ресурсы и операции, какие параметры и тела запросов они принимают, что возвращают и как защищены. По такому описанию и человек, и программа понимают возможности сервиса без доступа к его коду: из него строят документацию, генерируют клиентов и серверные заготовки, настраивают тестирование и шлюзы.

openapi: 3.0.3
info:
  title: API заказов
  version: 1.0.0
paths:
  /orders/{orderId}:
    get:
      summary: Получить заказ
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Заказ
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  status:
                    type: string
        '404':
          description: Заказ не найден

Редактор в «Помощнике SA»

Спецификация пишется слева в YAML или JSON, справа — документация в стиле Swagger UI; она обновляется по мере ввода, ошибки синтаксиса подсвечиваются в строках кода.
«Файл → Скачать» сохраняет спецификацию в YAML или JSON (в том числе с преобразованием формата).
Ctrl+клик (Cmd+клик на macOS) по $ref переходит к определению — в этом файле или в другом файле проекта.
ИИ-подсказки дописывают код у курсора, а кнопка «ИИ-ревью» проверяет спецификацию на соответствие принципам REST (на тарифах «Макс» и выше).
Кнопка «Try it out» в документации отправляет настоящий запрос из браузера: он дойдёт, только если сервер из servers доступен и разрешает запросы с сайта (CORS).

Документация описывает версию OpenAPI 3.0. Редактор показывает и спецификации 3.1 (они совместимы с 3.0 в большинстве конструкций; главное отличие — в 3.1 схемы полностью соответствуют JSON Schema 2020-12).

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

Документ OpenAPI — это JSON-объект, который можно записать в JSON или YAML (версии 1.2). Все имена полей чувствительны к регистру. Рекомендуется называть корневой файл openapi.yaml или openapi.json.

В YAML рекомендуется:

использовать только теги, которые есть в JSON Schema (строки, числа, логические значения, null, массивы, объекты);
ключи объектов делать строками — например, коды ответов записывать в кавычках: '200'.

Документ может состоять из одного файла или из нескольких, связанных ссылками $ref (см. раздел «Компоненты и ссылки»).

Типы данных

Типы данных соответствуют JSON Schema; поле format уточняет тип.

`type`	`format`	Описание
`integer`	`int32`	32-битное целое со знаком
`integer`	`int64`	64-битное целое со знаком
`number`	`float`	число с плавающей точкой
`number`	`double`	число двойной точности
`string`		строка
`string`	`byte`	данные в Base64
`string`	`binary`	произвольные двоичные данные (файл)
`boolean`		`true` / `false`
`string`	`date`	дата по RFC 3339: `2026-10-01`
`string`	`date-time`	дата и время по RFC 3339: `2026-10-01T12:30:00Z`
`string`	`password`	подсказка интерфейсу скрыть ввод

format — открытое поле: можно использовать и другие значения (email, uuid, uri), инструменты, которые их не знают, просто проигнорируют уточнение.

Описания и Markdown

Поля description поддерживают разметку CommonMark: абзацы, списки, выделение, ссылки, код. Многострочные описания в YAML удобно писать после |:

description: |
  Возвращает заказ по идентификатору.

  **Права:** владелец заказа или администратор.

Относительные ссылки

Ссылки в url и $ref могут быть относительными. Они разрешаются относительно адреса документа, в котором находятся (для servers.url — относительно адреса самого документа OpenAPI).

Документация основана на спецификации OpenAPI 3.0.0 (лицензия Apache 2.0), переведена и сокращена: оставлены конструкции, которые используются на практике и поддерживаются редактором.