В этом разделе мы углубимся в спецификацию OpenAPI. Мы будем использовать тот же API-интерфейс OpenWeatherMap, который мы использовали в других частях этого курса, в качестве контента для нашего документа OpenAPI. Используя этот API, мы создадим действительный документ спецификации OpenAPI, а затем изобразим его в интерактивной документации используя Swagger UI.
Общие ресурсы для изучения спецификации OpenAPI
Изучение спецификации OpenAPI займет какое-то время. Для изучения планируйте около двух недель погружения, работая с конкретным API в контексте спецификации, прежде чем освоиться с ним. По мере изучения спецификации OpenAPI используйте следующие ресурсы:
- Образцы документов спецификации OpenAPI. Эти образцы документов спецификации являются хорошей отправной точкой в качестве основы для документации спецификации. Они дают общее представление об общей форме документа спецификации.
- Руководство пользователя Swagger. Руководство пользователя Swagger дружелюбное, концептуальное и легкое для понимания. В нем нет детализации и точности документации по спецификации на GitHub, но во многих отношениях она более понятна и содержит больше примеров.
- Документация по спецификации OpenAPI. Техническая документация является технической и требует некоторого привыкания, но мы, несомненно, будем часто к ней обращаться при описании своего API. Это длинный одностраничный документ, искать можно с помощью
Ctrl+F.
Чем отличается руководство по OpenAPI/Swagger Тома Джонсона
Можно найти много учебных пособий по Swagger онлайн. В чем отличие этого руководства? Помимо сквозного пошагового руководства, использующего версию спецификации OpenAPI 3.0 (а не 2.0), и фактического API для контекста, здесь показано, как поля OpenAPI отображаются в пользовательском интерфейсе Swagger. В частности, демонстрируется, как и где каждое из полей OpenAPI отображается в Swagger UI.
Конечно, многие другие фрэймворки могут анализировать и отображать информацию в документе спецификации OpenAPI, но Swagger UI является одним из самых популярных. Swagger UI спонсируется SmartBear, той же компанией, которая активно инвестирует в инициативу OpenAPI и разрабатывает Swaggerhub. Их Инструментарий почти всегда синхронизирован с новейшими разработками. Swagger UI - активно разработанный и управляемый опен-сорс проект.
Показывая, как поля в спецификации отображаются в пользовательском интерфейсе Swagger, Том Джонсон надеется, что объекты и свойства спецификации приобретут большую актуальность и значение. Отображение пользовательского интерфейса Swagger - это всего лишь одна из возможностей визуального отображения информации о спецификации.
Терминология Swagger и OpenAPI
Прежде чем продолжить, уточним некоторые термины для тех, кто может быть незнаком с OpenAPI/Swagger:
- Swagger был оригинальным названием спецификации OpenAPI, но позже спецификация была изменена на OpenAPI, чтобы усилить открытую, непатентованную природу этого стандарта. Теперь «Swagger» относится к инструментам API, которые поддерживают спецификацию OpenAPI, а не к самой спецификации. Люди по-прежнему часто ссылаются на оба имени взаимозаменяемо, но «OpenAPI» - это то, как следует обращаться к спецификации.
- Smartbear - это компания, которая поддерживает и разрабатывает инструменты Swagger с открытым исходным кодом (Swagger Editor, Swagger UI, Swagger Codegen и другие). Они не владеют спецификацией OpenAPI, так как Linux Foundation поддерживает эту инициативу. Разработка спецификации OpenAPI ведется многими компаниями и организациями.
- «Документ спецификации OpenAPI» или «документ OpenAPI» - это Swagger-файл в формате YAML, который создается для описания API.
Другие определения находятся в Глоссарии API
Разберемся с некоторыми дополнительными дескрипторами JSON и YAML. Документ спецификации в нашем руководстве по OpenAPI использует YAML (который вкратце представлен здесь), но он также может быть создан и в JSON. JSON - это подмножество YAML, поэтому эти два формата являются практически взаимозаменяемыми (для структур данных, которые мы используем). В конечном счете, однако, спецификация OpenAPI является объектом JSON. Примечания к спецификации:
Другими словами, созданный документ OpenAPI является объектом JSON, но у нас есть возможность выразить JSON с использованием синтаксиса JSON или YAML. YAML более читабелен и является более распространенным форматом (см. Обсуждение API Handyman JSON против YAML), поэтому YAML используется только здесь. Документация спецификации OpenAPI на GitHub всегда показывает синтаксис JSON и YAML при отображении форматов спецификации. (Для более подробного сравнения YAML с JSON см. «Отношение к JSON» в спецификации YAML.)
YAML относится к структурам данных с тремя основными терминами: маппинг (отображения) (хэши / словари), последовательности (массивы / списки) и скаляры (строки / числа)» (см. «Введение» в YAML 1.2). Однако, поскольку спецификация OpenAPI является объектом JSON, он использует терминологию JSON - например, «объекты», «массивы», «свойства», «поля» и так далее. Поэтому содержимое будет показываться в формате YAML, но описываться будет с помощью терминологии JSON.
Каждый уровень в YAML (определенный отступом в два пробела) является объектом. В следующем коде california является объектом. animal, flower и bird являются свойствами объекта california.
california:
animal: Grizzly Bear
flower: Poppy
bird: Quail
В JSON это выглядит так:
{
"california": {
"animal": "Grizzly Bear",
"flower": "Poppy",
"bird": "Quail"
}
}
В спецификации часто используется термин «поле» в заголовках и именах столбцов таблицы при перечислении свойств для конкретного объекта. (Кроме того, идентифицируется два типа полей: объявляются «фиксированные» поля, уникальные имена, а «шаблонные» поля являются выражениями регулярных выражений.) Поля и свойства используются в спецификации OpenAPI как синонимы.
В коде ниже countries содержит объект с именем united_states, который содержит объект с именем california, который содержит несколько свойств со строковыми значениями:
countries:
united_states:
california:
animal: Grizzly Bear
flower: Poppy
bird: Quail
Ниже пример объекта demographics, содержащего массив:
demographics:
- population
- land
- rivers
И вот как он выглядит в JSON:
{
"demographics": [
"population",
"land",
"rivers"
]
}
Надеемся, что эти краткие примеры помогут понять терминологию, использованную в руководстве.
Начнем с общего представления
Если вы хотите получить общее представление о спецификации, взгляните на примеры 3.0 здесь, в частности спецификацию Petstore OpenAPI. Поначалу, вероятно, будет много непонятного, но постараемся получить представление о целом, прежде чем мы углубимся в детали. Посмотрим также на некоторые другие примеры в папке v.3.0.
Учебник OpenAPI шаг за шагом
Пошаговое руководство OpenAPI состоит из 8 шагов. Каждый шаг соответствует одному из объектов корневого уровня в документе OpenAPI.
- Шаг 1: Объект
openapi - Шаг 2: Объект
info - Шаг 3: Объект
servers - Шаг 4: Объект
paths - Шаг 5: Объект
components - Шаг 6: Объект
security - Шаг 7: Объект
tags - Шаг 8: Объект
externalDocs
Не обязательно создавать документ спецификации в этом порядке; порядок выбран, чтобы предоставить более конкретный путь и шаги к процессу.
В следующих разделах мы рассмотрим каждый из этих объектов один за другим и задокументируем текущий API OpenWeatherMap. Работа с каждым объектом корневого уровня индивидуально (а не документирование всего сразу) помогает уменьшить сложность спецификации.
components - это скорее объект хранения схем, определенных в других объектах, но чтобы избежать одновременного введения слишком большого количества данных, подождем, пока в руководстве components не будет полностью объяснено, как ссылаться на схему в одном объекте (используя $ref), который указывает на полное определение в components.С каждым шагом мы будем вставлять объект, над которым работаем, в редактор Swagger. На правой панели редактора Swagger будет отображаться интерфейс Swagger. (Помните, что один документ спецификации ничего не делает с вашим контентом. Для чтения и отображения документа спецификации требуются другие инструменты.)
Позже, когда мы узнаем больше о публикации документации, будет пояснение, как сконфигурировать интерфейс Swagger с нашим документом спецификации в качестве отдельного продукта. Для нашего примера API OpenWeatherMap вы можете увидеть спецификацию OpenAPI, отображаемую интерфейсом Swagger, по следующим ссылкам:
Миграция от OpenAPI 2.0 к 3.0
При наличии существующего документа спецификации, который проверяется на соответствие версии OpenAPI 2.0 и можно конвертировать его в OpenAPI 3.0 (или наоборот), можно использовать APIMATIC’s Transformer для его автоматического преобразования. (Можно использовать APIMATIC для преобразования документа спецификации во многие другие выходные данные, такие как RAML, API Blueprint или Postman.)
Чтобы увидеть разницу между версиями 2.0 и 3.0, можно скопировать примеры кода в отдельные файлы, а затем использовать приложение Diffmerge, чтобы выделить различия. В блоге Readme.io есть хорошая публикация: A Visual Guide to What’s New in Swagger 3.0
Полезные источники
Приступая к созданию файла спецификации OpenAPI, может пригодиться запись презентации Swagger / OpenAPI Питера Грюнбаума, а также его курс на Udemy.
Приготовились! Сейчас начнем узнавать, насколько мы готовы к техническому написанию API.