OpenAPI

Переводите поясняющие поля в YAML-документах OpenAPI 3.x, сохраняя пути, идентификаторы операций и ссылки.

Документ OpenAPI объединяет машиночитаемый контракт API и пояснения для тех, кто им пользуется. Обработчик файлов yaml-openapi выбирает поля title, description и summary по их расположению в YAML-документе OpenAPI 3.x. Пути, идентификаторы операций и ссылки остаются неизменными.

Сохраняйте контракт API неизменным #

В этом примере операция остаётся той же, а её пояснение можно перевести на другой язык:

yaml
openapi: 3.0.3
info:
  title: Order service
  version: 1.0.0
paths:
  /orders:
    get:
      operationId: listOrders
      summary: List your orders
      responses:
        "200":
          description: Orders retrieved

Обработчик выбирает заголовок, краткое описание и описание ответа. /orders, listOrders и 1.0.0 остаются без изменений. В выборку также входят информационные поля, описания тегов и внешней документации, описания путей и описательные поля внутри распознаваемых контейнеров схем и операций.

Проверьте примеры и значения по умолчанию, заданные в виде объектов в этих контейнерах. Вложенное свойство с именем title, description или summary тоже может попасть в выборку, даже если оно содержит данные из примера запроса или ответа. Другие значения схемы, например обычные строки перечислений и значения $ref, остаются без изменений.

Парсеру требуется YAML-отображение, в котором версия openapi начинается с 3.. Swagger 2.x, документы без версии и с другими версиями отклоняются. Поддержка JSON в OpenAPI не означает, что файл OpenAPI в формате JSON попадёт в выборку: этот обработчик рассчитан только на YAML.

Восстановление и повторное использование #

Текущий исходный документ задаёт дерево спецификации. Существующие формулировки сопоставляются по идентифицирующим признакам описательного поля и его вхождению. При сопоставлении также учитывается, к какой операции относится поле. Изменённые исходные описания нужно перевести заново, а для совпадающих полей без изменений можно повторно использовать готовый перевод.

Сериализатор YAML восстанавливает документ и может привести форматирование к единому виду. Следите за соответствием предыдущих версий исходной и переведённой спецификаций. Проверяйте перемещения полей и повторяющиеся описания, которые влияют на повторное использование переводов.

Выберите обработчик спецификации #

Явно укажите обработчик yaml-openapi для .yaml или .yml в конфигурации файлов CLI. Одного расширения недостаточно, чтобы отличить спецификацию API от каталога приложения. Универсальный обработчик YAML выберет гораздо больше строк, а YAML с локалями в корне требует другой структуры внешнего уровня.

Используйте конфигурацию CLI или GitHub, чтобы выбрать файлы и задать пути назначения. Перевод отдельных ключей через CLI для OpenAPI недоступен.

Проверьте контракт и прочитайте описания #

Проверьте восстановленный документ с помощью инструментов OpenAPI и сравните с исходным документом пути, идентификаторы операций, ссылки, обязательные поля и значения схемы. Затем прочитайте описания в готовом представлении, сверяя их с контрактом. Описание ответа, в котором изменилось условие или обещание, может ввести разработчиков в заблуждение, даже если спецификация остаётся корректной.