OpenAPI
Переводите поясняющие поля в YAML-документах OpenAPI 3.x, сохраняя пути, идентификаторы операций и ссылки.
Документ OpenAPI объединяет машиночитаемый контракт API и пояснения для тех, кто им пользуется. Обработчик файлов yaml-openapi выбирает поля title, description и summary по их расположению в YAML-документе OpenAPI 3.x. Пути, идентификаторы операций и ссылки остаются неизменными.
Сохраняйте контракт API неизменным #
В этом примере операция остаётся той же, а её пояснение можно перевести на другой язык:
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 и сравните с исходным документом пути, идентификаторы операций, ссылки, обязательные поля и значения схемы. Затем прочитайте описания в готовом представлении, сверяя их с контрактом. Описание ответа, в котором изменилось условие или обещание, может ввести разработчиков в заблуждение, даже если спецификация остаётся корректной.