В этом разделе мы углубимся в спецификацию OpenAPI. Мы будем использовать тот же API-интерфейс OpenWeatherMap, который мы использовали в других частях этого курса, в качестве контента для нашего документа OpenAPI. Используя этот API, мы создадим действительный документ спецификации OpenAPI, а затем изобразим его в интерактивной документации используя Swagger UI.
Общие ресурсы для изучения спецификации OpenAPI
Чем отличается руководство по OpenAPI/Swagger Тома Джонсона
Терминология Swagger и OpenAPI
Изучение спецификации OpenAPI займет какое-то время. В качестве оценки планируйте около двух недель погружения, работая с конкретным API в контексте спецификации, прежде чем освоиться с ним. По мере изучения спецификации OpenAPI используйте следующие ресурсы:
- Образцы документов спецификации OpenAPI. Эти образцы документов спецификации являются хорошей отправной точкой в качестве основы для документации спецификации. Они дают общее представление об общей форме документа спецификации.
- Руководство пользователя Swagger. Руководство пользователя Swagger дружелюбное, концептуальное и легкое для понимания. В нем нет детализации и точности документации по спецификации на GitHub, но во многих отношениях она более понятна и содержит больше примеров.
- Документация по спецификации OpenAPI. Техническая документация является технической и требует некоторого привыкания, но мы, несомненно, будем часто к ней обращаться при описании своего API. Это длинный одностраничный документ, искать можно с помощью
Ctrl+F.
В Интернете есть другие учебные пособия по Swagger / OpenAPI, но обязательно следуйте учебным пособиям для версии 3.0 API, а не 2.0. Версия 3.0 была выпущена в июле 2017 года. 3.0 существенно отличается от 2.0. (Версия 3.0.2 была выпущена в декабре 2017 года и внесла незначительные улучшения в версию 3.0. Обратите внимание, что всякий раз, при ссылке на 3.0, имеется в виду 3.x, что означает любой инкрементный выпуск точек из строки 3.0.)
Можно найти много учебных пособий по Swagger онлайн. В чем отличие этого руководства? Помимо сквозного пошагового руководства, использующего версию спецификации OpenAPI 3.0 (а не 2.0), и фактического API для контекста, здесь показано, как поля OpenAPI отображаются в пользовательском интерфейсе Swagger. В частности, демонстрируется, как и где каждое из полей OpenAPI отображается в Swagger UI.
Конечно, многие другие фрэймворки могут анализировать и отображать информацию в документе спецификации OpenAPI, но Swagger UI является одним из самых популярных. Swagger UI спонсируется SmartBear, той же компанией, которая активно инвестирует в инициативу OpenAPI и разрабатывает Swaggerhub. Их Инструментарий почти всегда синхронизирован с новейшими разработками. Swagger UI - активно разработанный и управляемый опен-сорс проект.
Показывая, как поля в спецификации отображаются в пользовательском интерфейсе Swagger, Том Джонсон надеется, что объекты и свойства спецификации приобретут большую актуальность и значение. Отображение пользовательского интерфейса Swagger - это всего лишь одна из возможностей визуального отображения информации о спецификации.
Прежде чем продолжить, уточним некоторые термины для тех, кто может быть незнаком с 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, который соответствует Спецификации OpenAPI, сам по себе является объектом JSON, который может быть представлен в формате JSON или YAML. (См. Format)
Другими словами, созданный документ 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 состоит из 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 и можно конвертировать его в 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.