Теги и расширения

Tag — тег

Теги группируют операции в документации. Операция ссылается на тег по имени в tags; в корневом массиве tags можно дать тегам описания и задать их порядок.

Поле	Описание
name	Обязательное. Имя тега.
description	Описание (CommonMark).
externalDocs	Внешняя документация.

tags:
  - name: Заказы
    description: Создание и отслеживание заказов
  - name: Каталог
    description: Товары и категории
    externalDocs:
      url: https://example.ru/docs/catalog

Каждое имя тега в корневом массиве должно быть уникальным. Теги, которые не перечислены в корне, тоже можно использовать в операциях — они будут показаны после описанных.

External Documentation

Поле	Описание
url	Обязательное. Адрес документации.
description	Описание ссылки.

Расширения спецификации (x-)

Почти в любой объект можно добавить свои поля с префиксом x- — для инструментов и договорённостей команды: генераторов кода, шлюзов, внутренних пометок. Значение — любой JSON.

paths:
  /orders:
    get:
      summary: Список заказов
      x-rate-limit: 100
      x-owner: team-orders
      responses:
        '200':
          description: Заказы

Стандартные инструменты игнорируют неизвестные расширения.

Рекомендации по проектированию REST API

Эти рекомендации не являются частью спецификации, но по ним проверяет спецификации «ИИ-ревью»:

• ресурсы — существительные во множественном числе: /orders, /orders/{orderId}/items; действия, которые не укладываются в CRUD, — отдельными подресурсами (POST /orders/{id}/cancel);
• методы по смыслу: GET не меняет данные, POST создаёт (ответ 201 и заголовок Location), PUT заменяет ресурс целиком, PATCH меняет частично, DELETE удаляет (204); PUT и DELETE идемпотентны;
• коды ответов: 400 — ошибка в запросе, 401 — нет авторизации, 403 — нет прав, 404 — не найдено, 409 — конфликт состояния, 422 — ошибка валидации данных, 429 — слишком много запросов;
• единый формат ошибок для всех операций, например Problem Details (RFC 9457): type, title, status, detail;
• коллекции — с пагинацией, фильтрацией и сортировкой через параметры запроса;
• у каждой операции — operationId, summary, теги и описанные ответы-ошибки;
• схемы — в components и через $ref, с required, форматами и примерами;
• версионирование — в адресе (/v1) или заголовке, одинаково по всему API;
• безопасность — схемы в securitySchemes и явный security для каждой операции (или корневой).