OpenAPI является спецификацией для описания REST API. Можно рассматривать спецификацию OpenAPI как спецификацию DITA. В DITA существуют определенные элементы XML, используемые для определения компонентов справки, а также требуемый порядок и иерархия для этих элементов. Различные инструменты могут читать DITA и создавать веб-сайт документации на основе информации.
В OpenAPI вместо XML существует набор объектов JSON с определенной схемой, которая определяет их наименование, порядок и содержимое. Этот файл JSON (часто выражается в YAML вместо JSON) описывает каждую часть API. Описывая API в стандартном формате, инструменты публикации могут программно анализировать информацию об API и отображать каждый компонент в стилизованном интерактивном виде.
Если есть желание сразу перейти к пошаговому справочнику по созданию документации в спецификации OpenAPI, см. Обзор руководства OpenAPI.
Взгляд на спецификацию OpenAPI
Автоматическая генерация файла OpenAPI из аннотаций кода
Подход: разработка по спецификации
Роль технического писателя в спецификации
Визуализация спецификации OpenAPI с помощью Swagger UI
Практическое занятие: Исследуем API PetStore в Swagger UI
Другие инструменты визуализации
Недостатки OpenAPI и Swagger UI
Ресурсы для дальнейшего чтения
Чтобы лучше понять спецификацию OpenAPI, давайте взглянем на некоторые выдержки из спецификации. Углубимся в каждый элемент в следующих разделах.
Официальное описание спецификации OpenAPI доступно в репозитории Github. Элементы OpenAPI - это paths, parameters, responses и security. Каждый из этих элементов является объектом JSON, который содержит свойства и массивы.
В спецификации OpenAPI ваши конечные точки это paths. Конечная точка /pet, в спецификации OpenAPI может выглядеть следующим образом:
paths:
/pets:
get:
summary: List all pets
operationId: listPets
tags:
- pets
parameters:
- name: limit
in: query
description: How many items to return at one time (max 100)
required: false
schema:
type: integer
format: int32
responses:
'200':
description: An paged array of pets
headers:
x-next:
description: A link to the next page of responses
schema:
type: string
content:
application/json:
schema:
$ref: "#/components/schemas/Pets"
default:
description: unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
Это формат YAML, взят из Swagger PetStore
Вот что значат объекты в этом коде:
/pets- конечна точка path;get- HTTP метод;parameters- список параметров конечной точки;responses- список ответов на запрос200- HTTP код статуса$refявляется ссылкой на другую часть реализации, где определяется ответ (вcomponents). OpenAPI имеет много$refссылок, подобных этой, чтобы сохранить код в чистоте и облегчить его повторное использование.
Может потребоваться некоторое время, чтобы понять спецификацию OpenAPI. Возьмем пару недель и несколько примеров спецификации, чтобы посмотреть, особенно в контексте фактического API. Спецификация OpenAPI достаточно общая, чтобы описать почти каждый API REST, поэтому некоторые части могут быть более применимыми, чем другие.
При создании спецификации OpenAPI, вместо того, чтобы работать в текстовом редакторе, можно написать свой код в редакторе Swagger. Редактор Swagger динамически проверяет контент, чтобы определить, является ли созданная спецификация валидной.
Если допустить ошибку при написании кода в редакторе Swagger, можно быстро исправить ее, прежде чем продолжить, вместо того, чтобы ждать запуска сборки и устранять ошибки.
Для формата спецификации у нас есть выбор работы JSON или YAML. Пример кода выше находится в YAML. У YAML официальное определение: «YAML не является языком разметки», что означает, что в YAML нет тегов разметки (<>), как в других языках разметки, таких как XML.
YAML зависим от пробелов и двоеточий, устанавливающих синтаксис объекта. Такое пространственно-чувствительное форматирование делает код более понятным для человек. Однако, иногда могут возникнуть сложности с расстановкой правильных интервалов.
Вместо того, чтобы кодировать документ в спецификации OpenAPI вручную, также можно автоматически сгенерировать его из аннотаций в программном коде. Этот подход, ориентированный на разработчиков, имеет смысл, если есть большое количество API-интерфейсов или если для технических писателей нецелесообразно создавать эту документацию.
Swagger предлагает множество библиотек, которые можно добавлять в свой программный код для создания документа в спецификации. Эти библиотеки Swagger анализируют аннотации, которые добавляют разработчики, и генерируют документ в спецификации OpenAPI. Эти библиотеки считаются частью проекта Swagger Codegen. Методы аннотации различаются в зависимости от языка программирования. Например, вот справочник по аннотированию кода с помощью Swagger для Scalatra. Для получения дополнительной информации о Codegen см. Сравнение инструментов автоматического генерирования кода API для Swagger по API Evangelist. Дополнительные инструменты и библиотеки см. В разделах «Интеграции и инструменты Swagger» и «Интеграция с открытым исходным кодом».
Хотя этот подход и «автоматизирует» генерацию спецификации, нужно еще понимать, какие аннотации добавить и как их добавить (этот процесс не слишком отличается от комментариев и аннотаций Javadoc). Затем нужно написать контент для каждого из значений аннотации (описывая конечную точку, параметры и т. Д.).
Короче говоря, поработать все нужно - автоматизированная часть заставляет библиотеки Codegen генерировать определения модели и действительный документ, который соответствует схеме OpenAPI. Тем не менее, многие разработчики взволнованы этим подходом, потому что он предлагает способ генерировать документацию из аннотаций кода, что разработчики годами делали с другими языками программирования, такими как Java (используя Javadoc) или C ++ (используя Doxygen). Они обычно считают, что генерация документации из кода приводит к меньшему отклонению документации. Документы, будут оставаться актуальными, если будут тесно связан с кодом.
Если идти по этому пути, нужно убедиться, что есть доступ к исходному коду для внесения изменений в аннотации. В противном случае разработчики будут писать документацию (что может и хорошо, но часто приводит к плохим результатам).
Можно сгенерировать свою спецификацию из аннотаций кода, но говорят, что автоматическая генерация - не лучший подход. Майкл Стоу (Michael Stowe) в статье Беспрепятственный REST: руководство по проектированию Perfect API рекомендует группам вручную реализовать спецификацию, а затем обрабатывать документ спецификации как документ, который разработчики используют при выполнении реального кодирования. Этот подход часто упоминается как «spec-first development».
Spec-first development это философия о том, как разрабатывать API более эффективно. Если вы следуете философии «сначала спецификация», вы сначала пишете спецификацию и используете ее в качестве контракта, к которому разработчики пишут код.
Другими словами, разработчики обращаются к спецификации, чтобы увидеть, как должны называться имена параметров, каковы должны быть ответы и так далее. После того, как этот «контракт» или «план» был принят, Стоу говорит, можно поместить аннотации в свой код (при желании), чтобы сгенерировать документ спецификации более автоматизированным способом. Но не стоит кодировать без предварительной спецификации.
Слишком часто команды разработчиков быстро переходят к кодированию конечных точек API, параметров и ответов, без пользовательского тестирования или исследования, соответствует ли API тому, что хотят пользователи. Поскольку управление версиями API-интерфейсов чрезвычайно сложно (необходимо поддерживать каждую новую версию в дальнейшем с полной обратной совместимостью с предыдущими версиями), есть желание избежать подхода «быстрый сбой», который так часто отмечают agile энтузиасты. Нет ничего хуже, чем выпустить новую версию вашего API, которая делает недействительными конечные точки или параметры, используемые в предыдущих выпусках. Постоянное версионирование в API может стать кошмаром документации.
Компания Smartbear, которая делает SwaggerHub (платформу для совместной работы команд над спецификациями API Swagger), говорит, что теперь для команд чаще встречается ручное написание спецификации, а не встраивание аннотаций исходного кода в программный код для автоматической генерации. Подход “spec-first development” в первую очередь помогает работать документации среди большего количества членов команды, нежели только инженеров. Определение спецификации перед кодированием также помогает командам создавать лучшие API.
Даже до создания API спецификация может генерировать ложный ответ, добавляя определения ответа в спецификацию. Мок-сервер генерирует ответ, который выглядит так, как будто он исходит от реального сервера, но это просто предопределенный ответ в коде, и кажется динамичным для пользователя.
В большинстве проектов Тома Джонсона разработчики были не очень хорошо знакомы с Swagger или OpenAPI, поэтому он обычно создавал документ спецификации OpenAPI вручную. Кроме того, он часто не имел доступа к исходному коду, и для разработчиков английский язык был не родным. Документация была для них сложным делом.
Возможно, и нам будут попадаться инженеры, не знакомые с Swagger или OpenAPI, но заинтересованные в использовании их в качестве подхода к документации API (подход, основанный на схемах, соответствует инженерному мышлению). Таким образом, нам, вероятно, придется взять на себя инициативу, чтобы направлять инженеров к необходимой информации, подходу и другим деталям, которые соответствуют лучшим практикам для создания спецификации.
В этом отношении технические писатели играют ключевую роль в сотрудничестве с командой в разработке спецификации API. Если придерживаться философии разработки, основанной на спецификациях, эта роль (техписателя) может помочь сформировать API до его кодирования и блокировки. Это означает, что может быть возможность влиять на имена конечных точек, консистенцию и шаблоны, простоту и другие факторы, которые влияют на разработку API (на которые, обычно, не влияют технические писатели).
После того, как получился действующий документ по спецификации OpenAPI, описывающий API, можно "скормить" эту спецификацию различным инструментам, чтобы проанализировать ее и сгенерировать интерактивную документацию, аналогичную примеру Petstore.
Наиболее распространенным инструментом, используемым для анализа спецификации OpenAPI, является Swagger UI. (Помните, что «Swagger» относится к инструментам API, тогда как «OpenAPI» относится к независимой от поставщика спецификации, не зависящей от инструмента.) После загрузки пользовательского интерфейса Swagger его довольно легко настроить с помощью собственного файла спецификации. Руководство по настройке Swagger UI есть в этом разделе.
Код пользовательского интерфейса Swagger генерирует экран, который выглядит следующим образом:
На изображении видно, как Swagger отображает спецификацию Open API
Можно ознакомиться с примером интеграции Swagger UI с примером API сервиса погоды, использованным в качестве примера курса.
Некоторые дизайнеры критикуют выпадающие списки Swagger UI как устаревшие. В то же время разработчики считают одностраничную модель привлекательной и способной уменьшать или увеличивать детали. Объединяя все конечные точки на одной странице в одном представлении, пользователи могут сразу увидеть весь API. Такое отображение дает пользователям представление в целом, что помогает уменьшить сложность и позволяет им начать. Во многих отношениях отображение Swagger UI является кратким справочным руководством по API.
Давайте познакомимся с пользовательским интерфейсом Swagger, используя Petstore.
- Переходим по ссылке Swagger Pet Store Demo
Как и в большинстве основанных на Swagger'е инструментов, в интерфейсе Swagger есть кнопка «Try it out». Для работы необходима авторизация в Swagger. Авторизация по нажатии на кнопку Authorize, в появившемся окне нужно вставить корректную информацию. При желании авторизоваться можно добавив любой номер в поле api_key и нажав Authorize. Окно авторизации Petstore предназначено только для демонстрации, так что окно можно просто закрыть.
Окно авторизации в Swagger UI
-
Разверните конечную точку Pet
-
Нажимаем на кнопку
Try it out. После нажатие пример значения в поле "Тело запроса" станет редактируемым.
Кнопка Try it out в Swagger UI
-
В примере заменяем значение
idна другое целое (не повторяющееся) число. Далее меняем значениеvalueна какое-нибудь узнаваемое (имя щенка -Puppy). -
Нажимаем
Execute
Выполнение примера Petstore запроса
Swagger UI отправляет запрос и показывает отправленный curl. В примере был отправлен curl:
curl -X POST "https://petstore.swagger.io/v2/pet" -H "accept: application/xml" -H "Content-Type: application/json" -d "{ \"id\": 1000, \"category\": { \"id\": 0, \"name\": \"string\" }, \"name\": \"Bentley\", \"photoUrls\": [ \"string\" ], \"tags\": [ { \"id\": 0, \"name\": \"string\" } ], \"status\": \"available\"}"Обратите внимание, что с параметром -d (data) параметр тела запроса экранируется и добавляется непосредственно в команду curl, а не загружается из файла (как описано в Общих командах curl, связанных с REST).
В разделе "Ответы" Swagger UI выдает ответ сервера. По умолчанию ответ возвращает XML:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Pet>
<category>
<id>0</id>
<name>string</name>
</category>
<id>1000</id>
<name>Bentley</name>
<photoUrls>
<photoUrl>string</photoUrl>
</photoUrls>
<status>available</status>
<tags>
<tag>
<id>0</id>
<name>string</name>
</tag>
</tags>
</Pet>Если выбрать в выпадающем списке "Response content type" JSON, то в ответе вернется JSON вместо XML.
- "Petstore" - является действующим API, питомец фактически создан. Для забавы развернем конечную точку GET / pet / {petId}, нажимаем
Try it out, вводимidпитомца, который использовали в предыдущей операции, а затем выполняем запрос. В ответе видим имя питомца, которое совпадает с тем, что ввели в предыдущем примере.
Помимо Swagger UI есть и другие инструменты, которые могут анализировать нашу документацию OpenAPI. Вот список из нескольких инструментов: Restlet Studio, Apiary, Apigee, Lucybot, Gelato, Readme.io, swagger2postman, отзывчивую тему swagger-ui, Postman Run Buttons и многое другое.
Swagger UI можно настроить по своему, чтобы вывод информации не выглядел однообразно: можно настроить цвета интерфейса Swagger, добавить собственный логотип, добавить других пользовательских стилей. Можно интегрировать Bootstrap, чтобы получить модальные окна, где пользователи могут генерировать свои коды авторизации. Можно даже добавить функции сворачивания/разворачивания в элементе description, чтобы предоставить больше информации пользователям.
Однако, помимо этих простых модификаций, потребуется немного мастерства веб-разработчика, чтобы существенно изменить отображение пользовательского интерфейса Swagger. Возможно, понадобятся навыки веб-разработки.
Несмотря на то, что Swagger обладает интерактивными возможностями апеллировать к желаниям пользователей «дай мне попробовать», у Swagger и OpenAPI есть некоторые недостатки:
- Информация только о ссылке: Во-первых, спецификация OpenAPI и выходные данные Swagger UI охватывают только документацию ссылки. OpenAPI предоставляет основу каждой конечной точки: описание, параметры, пример запроса и ответа. OpenAPI не содержит места для описания начала работы, информации о том, как получить ключи API, как запустить пример приложения, информацию об ограничениях скорости или о сотне других деталей, которые находятся в гайдах для разработчиков. Поэтому, несмотря на то, что есть этот крутой интерактивный инструмент, позволяющий пользователям исследовать и изучать наш API, мы все равно должны предоставить руководство пользователя. По аналогии, вывод Javadoc или Doxygen для основанной на библиотеке API не научит пользователей, как на самом деле использовать наш API. Нам все еще нужно описать сценарии использования класса или метода, объяснить, как настроить код, что делать с ответом, как устранить неполадки и т. Д. Короче говоря, писать реальные справочные и пошаговые руководства.
- Избыточность / дублирование информации: В OpenAPI потенциально есть два места, где описываются конечные точки и параметры (описание ссылки Swagger UI и руководство пользователя), и нужно либо синхронизировать их, встроить одно в другое, или иным образом указать связь между ними. Подробнее разберемся в разделе Интеграция Swagger с собственной документацией.
- Сложность рабочего процесса API: Сложность API также может создать ограничение в Swagger. Питер Грюнбаум, опубликовавший несколько учебных пособий по документированию API для Udemy, говорит, что автоматизированные инструменты, такие как Swagger, работают лучше всего для простых API. Если есть конечные точки, которые имеют сложные взаимозависимости и требуют специальных рабочих процессов настройки или другой не интуитивной обработки, простой характер пробного интерфейса Swagger может, вероятно, заставить пользователей почесать голову. Например, если нужно сначала настроить службу API, прежде чем конечная точка что-либо возвратит, а затем использовать одну конечную точку, чтобы получить определенный объект, который передается в параметры другой конечной точки, и т.д., функции
Try-it-outв Swagger UI не будет иметь большого смысла для пользователей без подробного руководства. - Запросы к реальным данным: Некоторые пользователи могут не осознавать, что нажатие кнопки
Try-it-outсоздает реальные вызовы для их собственных учетных записей на основе используемых ими ключей API. Смешивание использования исследовательской изолированной программной среды, такой как Swagger, с реальными данными может впоследствии создать головные боли, когда пользователи начнут спрашивать, как можно удалить все тестовые данные или почему их фактические данные теперь испорчены. Для этих сценариев лучше всего настроить песочницу или тестовую учетную запись для пользователей. Но это легче сказать, чем сделать. Можно обнаружить, что компания не предоставляет «песочницу» для тестирования API. Все вызовы API выполняются только для реальных данных. - Ограничения CORS: Можно столкнуться с ограничениями CORS (Cross-Origin Resource Sharing - обмен ресурсами между источниками) при выполнении вызовов API. Не все API принимают запросы, выполненные с веб-страницы. Если вызовы не выполняются, нужно открыть консоль JavaScript и проверить, не блокирует ли CORS запрос. Если это так, нужно попросить разработчиков внести коррективы, чтобы учесть запросы, инициированные из JavaScript на веб-страницах. См. CORS Support для более подробной информации.
- Проблематика обширных параметров тела запроса: конечные точки с длинными параметрами тела запроса, как правило, проблематичны. Один API может включать запросы с параметрами тела запроса длиной в сотни строк (тело запроса использовалось для настройки сервера API). С таким параметром тела запроса отображение пользовательского интерфейса Swagger оказалось непригодным для использования. Команда вернулась к гораздо более примитивным подходам (таким как таблицы) для перечисления всех параметров и их описания.
Несмотря на недостатки спецификации OpenAPI, он все же настоятельно рекомендуется ее для описания API. OpenAPI быстро становится средством для все большего и большего количества инструментов (от кнопок запуска Postman для почти каждой платформы API), для быстрого получения информации о нашем API и для превращения ее в доступную и интерактивную документацию. С помощью своей спецификации OpenAPI можно портировать свой API на многие платформы и системы, а также автоматически настраивать модульное тестирование и создание прототипов.
Swagger UI обеспечивает определенно хорошую визуальную форму для API. Можно легко увидеть все конечные точки и их параметры (например, краткий справочник). Основываясь на этой структуре, можно помочь пользователям понять основы вашего API.
Кроме того, изучение спецификации OpenAPI и описание своего API с его объектами и свойствами поможет расширить свой собственный словарь API. Например, станет понятно, что существует четыре основных типа параметров: параметры «пути», параметры «заголовка», параметры «запроса» и параметры «тела запроса». Типы данных параметров в REST: «Boolean», «number», «integer» или «string». В ответах содержатся «objects», содержащие «strings» или «arrays».
Короче говоря, реализация спецификации даст еще и представление о терминологии API, которая, в свою очередь, поможет описать различные компоненты своего API достоверными способами.
OpenAPI может не подходить для каждого API, но если API имеет довольно простые параметры, без большого количества взаимозависимостей между конечными точками, и если нет проблем исследовать API с данными пользователя, OpenAPI и Swagger UI могут быть мощным дополнением к документации. Можно давать пользователям возможность опробовать запросы и ответы.
С таким интерактивным элементом документация становится больше, чем просто информация. С помощью OpenAPI и Swagger UI мы создаем пространство для пользователей, которые одновременно могут читать нашу документацию и экспериментировать с нашим API. Эта комбинация имеет тенденцию предоставлять мощный опыт обучения для пользователей.
Вот источники для получения дополнительной информации об OpenAPI и Swagger: