Swagger – умная документация вашего RESTful web-API — обзор Junior back-end developer-а для новичков
Предисловие
Команда, в которой я сделала свои первые шаги на поприще написания промышленного кода, занималась разработкой удобного API к функциональности программного продукта на C# (для удобства назовем его, скажем, буквой E), существовавшего уже много лет и зарекомендовавшего себя на рынке с весьма положительной стороны. И здесь вроде бы у юного падавана пока не должно возникать вопросов, однако же представим себе, что ранее вы, скорей всего, конечно, писали собственные web-API, но вряд ли для широкой аудитории, а значит жили по принципу «Сам создал – сам пользуюсь», и если вдруг кого-то бы заинтересовала функциональность вашего API, то вы, наверное, кинули бы ему pdf-файл с подробной инструкцией (по крайней мере я бы сделала именно так). «Где посмотреть функционал апи» — спросила я тимлида ожидая получить ссылку на текстовый документ. «Загляни в Swagger» — ответил он.
Постой, как так получается, что продукт успешно функционирует уже давно, а API вы к нему пишете только сейчас?
Все верно, как такового удобного публичного API у E до недавнего времени не существовало. Фактически вся работа происходила через web-интерфейс, а back-end состоял из множества внутренних микросервисов, с которыми невозможно было интегрироваться извне без четкого понимания внутренней бизнес-логики, уж не говоря о том, что сами они на значительную долю состояли из легаси. Нужно было обратить внимание на клиентов, которые хотят непосредственно напрямую взаимодействовать с сервером, а значит предоставить им красивое и удобное API. Что для этого потребуется? Все, о чем было написано чуть раньше – самим взять и наладить работу со всеми внутренними микросервисами, а также обеспечить удобную и красивую документацию, сделав это красиво, понятно, и самое главное – коммерчески успешно.
Хорошо, так что же есть такое Swagger и в чем его полезность миру?
По сути Swagger – это фреймворк для спецификации RESTful API. Его прелесть заключается в том, что он дает возможность не только интерактивно просматривать спецификацию, но и отправлять запросы – так называемый Swagger UI, вот так это выглядит:
Как мы видим – полное описание методов, включая модели, коды ответов, параметры запроса – в общем, наглядно.
И как это работает?
Отличное руководство для внедрения Swagger в ASP.NET Core
с нуля есть вот в этой этой статье.
Идея в конфигурации отображения с помощью специальных аннотаций у методов API, вот пример:
Swagger Codegen
Если очень хочется, то можно сгенерировать непосредственно клиента или сервер по спецификации API Swagger, для этого нужен генератор кода Swagger-Codegen. Описание из документации, думаю, пояснять не требуется:
This is the Swagger Codegen project, which allows generation of API client libraries (SDK generation), server stubs and documentation automatically given an OpenAPI Spec. Currently, the following languages/frameworks are supported:
Прочая информация, в частности инструкция по использованию, представлена здесь:
Общая информация
Swagger: что это такое, и как с ним работать?
Для взаимодействия с любой программой используется API. Он может быть закрытым для внешнего взаимодействия или открытым. В любом случае разработчикам следует уделять внимание его спецификации. Это в том числе нужно для того, чтобы новые члены команды быстрее и проще вовлекались в проект.
Ручное формирование документации — утомительное занятие. Поэтому разработчики придумали Swagger. С его помощью на основе кода можно автоматически сгенерировать спецификации API.
Что такое Swagger?
Swagger — это набор инструментов, которые помогают описывать API. Благодаря ему пользователи и машины лучше понимают возможности REST API без доступа к коду. С помощью Swagger можно быстро создать документацию и отправить ее другим разработчикам или клиентам.
В 2015 году проект Swagger сделали открытым и передали OpenAPI Initiative. Теперь сама спецификация называется OpenAPI. Swagger — инструментарий для работы с OpenAPI, название которого используется в коммерческих и некоммерческих продуктах. Если кто-то называет саму спецификацию Swagger, то это не совсем верно.
Документ спецификации OpenAPI использует YAML, но также может быть написан в формате JSON. Сам по себе он является объектом JSON.
Основные подходы
Swagger предлагает два основных подхода к генерированию документации:
Первый подход проще. Мы добавляем зависимости в проект, конфигурируем настройки и получаем документацию. Сам код из-за этого может стать менее читабельным, документация тоже не будет идеальной. Но задача минимум решена — код задокументирован.
Чтобы пользоваться вторым подходом, нужно знать синтаксис Swagger. Описания можно готовить в формате YAML/JSON. Можно упростить эту задачу, используя Swagger Editor. Конечно, второй подход позволяет сделать документацию более качественной и кастомной для каждого конкретного проекта и его особенностей, к тому же все не так сложно как может показаться, это потребует минимальных дополнительных усилий.
Swagger Core
Это Java-реализация спецификации. Для ее использования потребуется:
Для его внедрения в проект используются две зависимости. Вот примеры:
Другой способ — настроить maven-плагин. Тогда описания при сборке проекта будут генерироваться в файл YAML. Пример:
После настройки конфигурации мы получим аннотации, которые можно использовать для документирования кода.
| Аннотация | Использование |
| @Operation | Для описания операции или метода HTTP |
| @Parameter | Для представления одного параметра в операции |
| @RequestBody | Для представления тела запроса в операции |
| @ApiResponse | Для представления тела ответа в операции |
| @Tag | Для представления тегов операции или определения OpenAPI |
| @Server | Для представления серверов операции или определения OpenAPI |
| @Callback | Для описания набора запросов |
| @Link | Для представления ссылки времени разработки для ответа |
| @Schema | Для определения входных и выходных данных |
| @ArraySchema | Для определения входных и выходных данных для типов массивов |
| @Content | Для представления схемы и примеров для мультимедиа |
| @Hidden | Для скрытия ресурса, операции или свойства |
Swagger Codegen
Это проект для автоматического генерирования клиентских библиотек API, заглушек сервера и документации. Поддерживает большое количество технологий. Посмотреть полный список можно в репозитории Swagger Codegen на GitHub.
В этом же репозитории вы найдёте примеры того, как можно генерировать документацию, используя различные шаблоны.
| API клиенты | ActionScript, Ada, Apex, Bash, C#, C++, Clojure, Dart, Elixir, Elm, Eiffel, Erlang, Go, Groovy, Haskell, Java (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy, Vertx, Google API Client Library for Java, Rest-assured), Kotlin, Lua, Node.js, Objective-C, Perl, PHP, PowerShell, Python, R, Ruby, Rust (rust, rust-server), Scala (akka, http4s, swagger-async-httpclient), Swift (2.x, 3.x, 4.x, 5.x), Typescript |
| Заглушки | Ada, C# (ASP.NET Core, NancyFx), C++ (Pistache, Restbed), Erlang, Go, Haskell (Servant), Java (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, RestEasy, Play Framework, PKMST), Kotlin, PHP (Lumen, Slim, Silex, Symfony, Zend Expressive), Python (Flask), NodeJS, Ruby (Sinatra, Rails5), Rust (rust-server), Scala (Finch, Lagom, Scalatra) |
| Генераторы документации | HTML, Confluence Wiki |
| Файлы конфигурации | Apache2 |
| Другое | JMeter для нагрузочного тестирования |
Плюсы Swagger Codegen:
Чтобы добавить Swagger Codegen в проект, используйте зависимость:
Как и в случае с Swagger Core, можно настроить maven-плагин для генерации клиента или мок-сервера.
Swagger Codegen предоставляет следующие команды:
Swagger UI
Swagger UI визуализирует ресурсы OpenAPI и взаимодействие с ними без отображения логики реализации. Этот инструмент берет спецификацию и превращает ее в интерактивный проект, где можно выполнять разные запросы для тестирования API.
Swagger Editor
Это онлайн-редактор для изменения и проверки API внутри браузера. Позволяет просматривать документацию в реалтайме. С его помощью можно создать описания, а затем использовать их с полным набором инструментов для генерации документации.
Плюсы Swagger Editor:
Верхний уровень спецификации OpenAPI 3.0 содержит восемь объектов. Внутри этих верхнеуровневых объектов есть много вложенных объектов. Давайте далее последовательно рассмотрим все объекты верхнего уровня.
Первое и самое важное свойство в документации. Объект содержит информацию о спецификации OpenAPI. Пример:
В объекте info содержится основная информация об API: заголовок, описание, версия, ссылки на лицензию, обслуживание, контактные данные. Не все свойства обязательны к заполнению.
Объект содержит базовый путь, который используется в запросах через API. Под базовым путём понимается часть адреса, которая находится перед конечной точкой. Servers можно гибко настраивать, например, указывая несколько адресов для тестирования:
В этом объекте хранятся различные схемы спецификации. Схемы позволяют заметно ускорить процесс составления описаний. Например:
Теперь можно ссылаться на эту схему и при необходимости без проблем дополнять её новыми полями.
Объект для объявления того, какие механизмы безопасности можно использовать в API.
Например, требование безопасности OAuth2 :
В этом объекте можно указать дополнительную информацию. Например:
Онлайн-редактор Swagger позволяет удобно работать над документацией со спецификацией. Он предлагает разделенный интерфейс. Слева вы пишете спецификацию, а справа видите отображение Swagger UI. В него даже можно отправлять запросы, чтобы сразу проверить правильность кода.
Использование Petstore для знакомства
Авторизация
Прежде всего нужно авторизоваться. Для этого нажмите на кнопку Authorize и заполните необходимую информацию.
В примере используется модель авторизации OAuth 2.0. На самом деле, код представлен в демонстрационных целях, никакой реальной логики за авторизацией нет. Так что можно просто закрыть окно.
Создание запроса
Создадим первый запрос к API. Для этого:
Проверка результата
Напоследок выполним ещё один запрос, чтобы убедиться, что питомец создан.
В ответе должно отобразиться имя созданного ранее питомца.
Это пример очень простой документации, которая позволяет быстро проверить работу доступных методов. Вы можете создать такой сайт самостоятельно или встроить интерфейс Swagger на страницу существующего ресурса — например, в справку о работе своего сервиса.
Как выглядят сайты с документацией Swagger UI
Вот ещё несколько примеров реализации Swagger:
Обращает на себя внимание краткость документации, реализованной с помощью Swagger. Это объясняется тем, что сам по себе Swagger UI предназначен для интерактивного взаимодействия. Нет смысла читать пространные описания, когда можно просто выполнять указанные запросы и проверять, какие ответы приходят.
Как встроить Swagger UI в существующий сайт
Чтобы встроить Swagger UI на свой сайт:
Отображение документации можно проверить локально. Если всё в порядке, загрузите папку dist (ее можно переименовать) на сервер и добавьте документацию на существующий сайт.
Заключение
Swagger — удобный инструмент для создания документации API, который помогает разработчикам сэкономить время. Он предлагает несколько решений для интеграции в проект и формирования интерактивной версии документации, с которой будет удобно взаимодействовать другим разработчикам, внешним пользователям, клиентам.
Чтобы разобраться со Swagger дополнительно, посмотрите эти видео.
Например, вот доклад технического писателя из «Яндекса» о том, что такое вообще API и как работать со Swagger. Много времени также уделено практической части — в ней делается простой Swagger, который затем отображается в Swagger UI и в документации.
Ещё одно классное видео — подробное объяснение, как использовать Swagger:
Документация Java REST API с помощью Swagger 2
Вступление
Что такое Суэггер?
Swagger-наиболее широко используемый инструмент для создания API, совместимых со спецификацией Open API (OAS).
Swagger сам по себе представляет собой набор инструментов с открытым исходным кодом, созданных по всему ДОМУ, которые могут помочь вам разрабатывать, создавать, документировать и генерировать документы REST API для веб-сервисов RESTful.
Наиболее заметными инструментами чванства являются:
Создание приложения
Интеграция Swagger 2 в приложение Spring Boot происходит довольно быстро и легко с помощью некоторых инструментов, которые мы уже используем изо дня в день.
Самый простой способ начать с проекта загрузки со скелетной пружиной, как всегда, – использовать href=” https://start.spring.io/”>Инициализация Весны. href=” https://start.spring.io/”>Инициализация Весны.
Выберите предпочитаемую версию Spring Boot и сгенерируйте ее как проект Maven, и все готово!
Чтобы включить Swagger 2 самостоятельно, вам нужно будет добавить пару зависимостей к вашему pom.xml файл:
После полной настройки нашего проекта и проверки наших зависимостей мы можем продолжить и создать простую конечную точку REST, которую мы представим в документации позже:
После этого давайте продолжим и создадим еще одну конечную точку REST – Пользовательский ресурс :
Оба этих класса зависят от пользователя модели:
Включение Swagger2
Сейчас самое время включить Wagger2 в нашем приложении, определив для него класс конфигурации.
Класс конфигурации должен быть аннотирован @Configuration – стандартной аннотацией Spring и @EnableSwagger2 аннотациями, чтобы включить платформу для вашего приложения Spring Boot.
Порядок этих аннотаций не важен:
Для этой цели мы определим Компонент с именем Список в классе конфигурации.
С другой стороны, мы можем использовать Селекторы обработчиков запросов.any() для создания документации для всех пакетов.
Метод paths() дополнительно определяет, для каких путей в наших API мы хотим создать документацию. Все наши конечные точки имеют “/v1”, поэтому в нашем случае он включает в себя все конечные точки. Однако это может быть не всегда так.
Пользовательский интерфейс Swagger
Давайте использовать Swagger UI для наблюдения за всеми нашими конечными точками REST, созданными Swagger.
Чтобы использовать пользовательский интерфейс Swagger, нам нужно добавить зависимость для него в ваш pom.xml файл:
Git Essentials
Ознакомьтесь с этим практическим руководством по изучению Git, содержащим лучшие практики и принятые в отрасли стандарты. Прекратите гуглить команды Git и на самом деле изучите это!
Как вы можете видеть, обе наши конечные точки находятся здесь – привет-ресурс и пользовательский ресурс, с соответствующими методами внутри. Имена методов определены справа, как вы можете видеть.
Мы можем использовать этот пользовательский интерфейс для тестирования наших конечных точек:
Нас встретит тело ответа “Привет, мир” и код ответа 200, что означает, что он работает так, как задумано.
То же самое, что и для GET/v1/пользователя из класса UserResource :
Нас встретят информацией, относящейся к пользователю, которого мы создали ранее.
Настройка Swagger2
Иногда компаниям и командам необходимо настраивать поведение Swagger 2, добавляя пользовательские сообщения и операции, чтобы адаптировать использование платформы к своим собственным потребностям.
Конструктор Epi info ожидает:
Мы можем переопределять имена методов с помощью аннотаций.
Аннотация @ApiOperation позволяет нам переопределить конечную точку и ее тип ответа. Swagger 2 также позволяет переопределять ответные сообщения по умолчанию методов HTTP|/.
Вы можете использовать аннотацию @ApiResponse для документирования других ответов в дополнение к обычному HTTP 200 OK :
Давайте взглянем на пользовательский интерфейс:
При расширении привет-ресурс мы видим, что правая часть документации обновилась. Кроме того, в ответных сообщениях обновлен предоставленный нами код и возвращаемый тип из аннотации @Api на уровне класса.
Свойства модели
Swagger2 предоставляет нам набор аннотаций для управления моделями с большим контролем:
Нам нужно будет обновить наш Пользовательский ресурс контроллер аннотацией @Api на уровне класса.
В Swagger 2 эта аннотация используется для применения определений ко всем операциям, определенным в ней, в отличие от ее использования в предыдущих версиях, где она объявляла ресурсы:
После обновления API давайте обновим и модель:
“Пример значения” показывает только значения по умолчанию.
Вывод
Каждый день компании и частные лица начинают использовать Swagger в качестве предпочтительного инструмента для предоставления API REST третьим лицам.
Используя инструменты Swagger, вы можете создавать код на основе документации API, а также создавать красивую интерактивную документацию. Это одновременно экономит время и усилия и обеспечивает стандарт для людей, с которыми можно работать.
Знакомство со спецификациями OpenAPI и Swagger
OpenAPI является спецификацией для описания REST API. Можно рассматривать спецификацию OpenAPI как спецификацию DITA. В DITA существуют определенные элементы XML, используемые для определения компонентов справки, а также требуемый порядок и иерархия для этих элементов. Различные инструменты могут читать DITA и создавать веб-сайт документации на основе информации.
В OpenAPI вместо XML существует набор объектов JSON с определенной схемой, которая определяет их наименование, порядок и содержимое. Этот файл JSON (часто выражается в YAML вместо JSON) описывает каждую часть API. Описывая API в стандартном формате, инструменты публикации могут программно анализировать информацию об API и отображать каждый компонент в стилизованном интерактивном виде.
Взгляд на спецификацию OpenAPI
Чтобы лучше понять спецификацию OpenAPI, давайте взглянем на некоторые выдержки из спецификации. Углубимся в каждый элемент в следующих разделах.
Это формат YAML, взят из Swagger PetStore
Вот что значат объекты в этом коде:
Проверка спецификации
При создании спецификации OpenAPI, вместо того, чтобы работать в текстовом редакторе, можно написать свой код в редакторе Swagger. Редактор Swagger динамически проверяет контент, чтобы определить, является ли созданная спецификация валидной.
Если допустить ошибку при написании кода в редакторе Swagger, можно быстро исправить ее, прежде чем продолжить, вместо того, чтобы ждать запуска сборки и устранять ошибки.
YAML зависим от пробелов и двоеточий, устанавливающих синтаксис объекта. Такое пространственно-чувствительное форматирование делает код более понятным для человека. Однако, иногда могут возникнуть сложности с расстановкой правильных интервалов.
Автоматическая генерация файла OpenAPI из аннотаций кода
Вместо того, чтобы кодировать документ в спецификации OpenAPI вручную, также можно автоматически сгенерировать его из аннотаций в программном коде. Этот подход, ориентированный на разработчиков, имеет смысл, если есть большое количество API-интерфейсов или если для технических писателей нецелесообразно создавать эту документацию.
Swagger предлагает множество библиотек, которые можно добавлять в свой программный код для создания документа в спецификации. Эти библиотеки Swagger анализируют аннотации, которые добавляют разработчики, и генерируют документ в спецификации OpenAPI. Эти библиотеки считаются частью проекта Swagger Codegen. Методы аннотации различаются в зависимости от языка программирования. Например, вот справочник по аннотированию кода с помощью Swagger для Scalatra. Для получения дополнительной информации о Codegen см. Сравнение инструментов автоматического генерирования кода API для Swagger по API Evangelist. Дополнительные инструменты и библиотеки см. В разделах «Интеграции и инструменты Swagger» и «Интеграция с открытым исходным кодом».
Хотя этот подход и «автоматизирует» генерацию спецификации, нужно еще понимать, какие аннотации добавить и как их добавить (этот процесс не слишком отличается от комментариев и аннотаций Javadoc). Затем нужно написать контент для каждого из значений аннотации (описывая конечную точку, параметры и т. Д.).
Если идти по этому пути, нужно убедиться, что есть доступ к исходному коду для внесения изменений в аннотации. В противном случае разработчики будут писать документацию (что может и хорошо, но часто приводит к плохим результатам).
Подход: разработка по спецификации
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 с помощью Swagger UI
После того, как получился действующий документ по спецификации 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.
👨💻 Практическое занятие: Исследуем API PetStore в Swagger UI
Давайте познакомимся с пользовательским интерфейсом Swagger, используя Petstore.
Окно авторизации в Swagger UI
Разворачиваем конечную точку Pet
Выполнение примера Petstore запроса
Swagger UI отправляет запрос и показывает отправленный curl. В примере был отправлен curl:
В разделе “Ответы” Swagger UI выдает ответ сервера. По умолчанию ответ возвращает XML:
Если выбрать в выпадающем списке “Response content type” JSON, то в ответе вернется JSON вместо XML.
Другие инструменты визуализации
Помимо Swagger UI есть и другие инструменты, которые могут анализировать нашу документацию OpenAPI. Вот список из нескольких инструментов: Restlet Studio, Apiary, Apigee, Lucybot, Gelato, Readme.io, swagger2postman, отзывчивую тему swagger-ui, Postman Run Buttons и многое другое.
Кастомизация Swagger UI
Однако, помимо этих простых модификаций, потребуется немного мастерства веб-разработчика, чтобы существенно изменить отображение пользовательского интерфейса Swagger. Возможно, понадобятся навыки веб-разработки.
Недостатки OpenAPI и Swagger UI
Несмотря на то, что Swagger обладает интерактивными возможностями апеллировать к желаниям пользователей «дай мне попробовать», у Swagger и OpenAPI есть некоторые недостатки:
Некоторые утешения
Несмотря на недостатки спецификации 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: