Шаг 1: объект openapi |
> | Шаг 2: объект info |
> | Шаг 3: объект servers |
> | Шаг 4: объект paths |
> | Шаг 5: объект components |
> | Шаг 6: объект security |
> | Шаг 7: объект tags |
> | Шаг 8: объект externalDocs |
Обзор руководства OpenAPI
Прежде чем перейти к первому шагу учебного руководства по OpenAPI, нужно прочитать обзор руководства по OpenAPI (если еще не читали), чтобы понять суть этого учебного пособия. Вкратце, это руководство по OpenAPI уникально в следующих отношениях:
- Это руководство OpenAPI показывает спецификацию в контексте API сервиса прогноза погоды, представленного ранее в этом курсе.
- В руководстве показано, как информация спецификации отображается в интерфейсе Swagger.
- Руководство OpenAPI является выдержкой из спецификации OpenAPI, и из комментариев спецификации OpenAPI.
- В руководстве OpenAPI охвачена версия 3.0 спецификации OpenAPI, которая является последней версией.
Корневые объекты в спецификации OpenAPI
На верхнем уровне в спецификации OpenAPI 3.0 существует восемь объектов. Внутри этих верхнеуровневых объектов есть много вложенных объектов, но на верхнем уровне есть только следующие объекты:
Весь документ (объект, содержащий восемь объектов корневого уровня) называется документом OpenAPI. По принятому соглашению документу присваивают имя openapi.yml.
Редактор Swagger
Для работы над документацией со спецификацией используется онлайн-редактор Swagger. Редактор Swagger имеет разделенное представление: слева пишем код спецификации, а справа видим полнофункциональный дисплей Swagger UI. Можно даже отправлять запросы из интерфейса Swagger в этом редакторе.
Редактор Swagger проверит контент в режиме реального времени, и укажет ошибки валидации, во время кодирования документа спецификации. Не стоит беспокоиться об ошибках, если отсутствуют X-метки в коде, над которым идет работа.
Полезно хранить текстовый файл локально, (например в редакторе Atom), со спецификацией в автономном режиме, и работать с содержимым документа в онлайн-редакторе Swagger. По окончании рабочего дня копировать и сохранять содержимое в свой локальный файл. Хотя, редактор Swagger достаточно хорошо кэширует содержимое (для этого не нужно очищать кеш браузера), поэтому скорее всего, локальный файл в качестве резервной копии не понадобится.
При желании можно приобрести подписку на SwaggerHub, и хранить содержимое спецификации в облаке (SwaggerHub имеет редактор, идентичный пользовательскому интерфейсу Swagger), в своем профиле. SwaggerHub - это инструмент премиум-класса для открытого и бесплатного редактора Swagger.
👨💻 Добавляем объект openapi
Переходим в редактор Swagger и выбираем File > Clear editor. Оставим эту вкладку открытой пока изучаем руководство по OpenAPI, так как будем обновлять документ спецификации с каждым шагом.
Введем первое свойство корневого уровня для документа спецификации: openapi. В объекте openapi указываем версию спецификации OpenAPI для проверки. Последняя версия 3.0.2.
openapi: "3.0.2"
Пока мы не добавим сюда дополнительную информацию, будут отображаться сообщения об ошибках и примечания, например: «No operations defined in spec!». Все в порядке - на следующем шаге мы увидим дополнительную информацию.
Версия 3.0 была выпущен 2017-07-26, а 3.0.2 - 10-08-2018 (см. «История версий»). Большая часть информации и примеров в Интернете, а также вспомогательные инструменты часто фокусируются только на 2.0. Даже если вы заблокированы для работы для версии 2.0, можно кодировать спецификацию в 3.0, а затем воспользоваться инструментом APIMATIC Transformer, для преобразования спецификации 3.0 в 2.0. Обратная конвертация из 2.0 в 3.0 там тоже доступна.
Представление в Swagger UI
Объект openapi не такой большой, и сейчас не хватает контента для проверки спецификации. Но когда мы позже визуализируем свой документ спецификации, мы увидим, что тег «OAS3» появится справа от имени API.
На сервере Swagger UI использует версию спецификации 3.0.2 для проверки вашего контента.
На приведенном выше снимке экрана версия 2.5 относится к версии API, а не к версии спецификации OpenAPI.