Swagger как сделать документацию

Руководство Swagger UI

Swagger UI предоставляет Фреймворк, который читает спецификацию OpenAPI. и создает веб-страницу с интерактивной документацией. В этом руководстве показано, как интегрировать документ спецификации OpenAPI в интерфейс Swagger.

Концептуальный обзор OpenAPI и Swagger можно посмотреть в разделе Знакомство со спецификациями OpenAPI и Swagger. Пошаговое руководство по созданию документа спецификации OpenAPI смотрим в Обзоре руководства OpenAPI 3.0.

Обзор Swagger UI

Swagger UI — один из самых популярных инструментов для создания интерактивной документации. Swagger UI создает интерактивную консоль API для экспериментов с запросами в реальном времени. Кроме того, Swagger UI (активно управляемый проект с лицензией Apache 2.0) поддерживает последнюю версию спецификации OpenAPI (3.x) и интегрируется с другими инструментами Swagger.

Прежде чем мы углубимся в Swagger, нужно прояснить ключевые термины.

Swagger

Относится к инструментам API, связанным со спецификацией OpenAPI. Некоторыми из этих инструментов являются Swagger Editor, Swagger UI, Swagger Codegen, SwaggerHub и другие. Всеми инструментами управляет компания Smartbear. Для получения дополнительной информации см. Инструменты Swagger. «Swagger» являлся изначально оригинальным названием спецификации OpenAPI, но позже имя было изменено на OpenAPI, чтобы усилить открытый, не лицензионный характер стандарта. Люди иногда ссылаются на оба имени взаимозаменяемо (особенно на старых веб-страницах), но «OpenAPI» — это то, как следует обращаться к спецификации. Дополнительные сведения о разнице между OpenAPI и Swagger см. В разделе «В чем разница между Swagger и OpenAPI?».

OpenAPI

Официальное название спецификации OpenAPI. Спецификация OpenAPI предоставляет набор свойств, которые можно использовать для описания REST API. Рабочий, валидный документ можно использовать для создания интерактивной документации, создания клиентских SDK, запуска модульных тестов и многого другого. Подробности спецификации можно изучить на GitHub по адресу https://github.com/OAI/OpenAPI-Specification. В рамках инициативы Open API с Linux Foundation спецификация OpenAPI направлена ​​на то, чтобы быть независимой от производителя (многие компании участвуют в ее разработке).

Swagger Editor

Онлайн-редактор, который проверяет документацию OpenAPI на соответствие правилам спецификации OpenAPI. Редактор Swagger помечает ошибки и дает советы по форматированию.

Swagger UI

Веб-фрэймворк (на GitHub), который анализирует документ в спецификации OpenAPI и создает веб-страницу интерактивной документации. Swagger UI — это инструмент, который превращает спецификацию в подобный Petstore-сайт.

Swagger Codegen

Генерирует код SDK для множества различных платформ (таких как Java, JavaScript, Scala, Python, PHP, Ruby, Scala и другие). Код SDK помогает разработчикам интегрировать API на конкретной платформе и обеспечивает более надежные реализации, которые могут включать в себя больше масштабирования, многопоточности и т.д.. В общем, SDK — это наборы инструментов для реализации запросов, сделанных с помощью API. Swagger Codegen генерирует клиентские SDK практически на каждом языке программирования. См. Swagger Codegen для получения дополнительной информации. Смотрите также SDK и примеры приложений.

Знакомство со Swagger при помощи Petstore

Чтобы лучше понять интерфейс Swagger, давайте рассмотрим пример Swagger Petstore. В примере Petstore сайт генерируется с помощью Swagger UI.

Конечные точки сгруппированы следующим образом:

Авторизация запроса

Прежде чем делать какие-либо запросы, нужна авторизация. Нажимаем кнопку Authorize и заполняем информацию, требуемую в окне «Авторизация», изображенном ниже:

Пример Petstore имеет модель безопасности OAuth 2.0. Код авторизации только для демонстрационных целей. Нет никакой реальной логики авторизации этих запросов, поэтому просто закрываем окно Авторизации.

Создание запроса

Теперь создадим запрос:

• Разворачиваем конечную точку POST Pet
• Нажимаем кнопку Try it out

После того, как мы нажмем кнопку Try it out , значение примера в поле «Тело запроса» станет редактируемым.

• В поле «Example Value» изменяем первое значение id на случайное целое число, например 193844 . Также значение второго name на другое (имя вашего питомца).
• Нажимаем Execute .

Пользовательский интерфейс Swagger отправляет запрос и показывает отправленный curl. Раздел Ответы показывает ответ. (Если выбрать JSON вместо XML в раскрывающемся списке «Response content type», формат ответа будет показан в формате JSON.)

Проверка создания питомца

1. Разворачиваем точку GET /pet/
2. Нажимаем кнопку Try it out
3. Вводим ID питомца, который использовали в предыдущей операции. (Если забыли ID, посмотрите на конечную точку POST Pet, чтобы проверить значение.)
4. Нажимаем Execute . В ответе мы должны увидеть имя нашего питомца.

Примеры сайтов с документаций по Swagger UI

Прежде чем мы перейдем к другому API с этим пособием по Swagger (кроме демонстрации Petstore), посмотрим на другие реализации Swagger:

Некоторые из этих сайтов выглядят одинаково, но другие, такие как The Movie Database API и Zomato, были легко интегрированы в остальную часть их сайта документации.

Глядя на примеры, можно заметить краткость документации в реализации Swagger. Эта краткость объясняется тем, что дисплей Swagger предназначен для интерактивного взаимодействия, где можно опробовать вызовы и посмотреть ответы — используя свой собственный ключ API, чтобы увидеть свои собственные данные. такой подход получил название: «учись, практикуясь». Кроме того, Swagger UI охватывает только документацию конечных точек. Концептуальные разделы обычно рассматриваются в отдельном руководстве.

��‍�� Практическое занятие: Создание спецификации OpenAPI в Swagger UI

На этом занятии мы создадим документацию в Swagger UI в спецификации OpenAPI. Если вы используете один из предварительно созданных файлов OpenAPI, вы можете увидеть демонстрацию того, что мы создадим здесь: OpenWeatherMap Swagger UI или Sunrise/sunset Swagger UI).

Для интеграции спецификации OpenAPI в Swagger UI:

• Подготавливаем действительный документ спецификации OpenAPI:
  • Инструкции по созданию документа спецификации OpenAPI с нуля см. В обзоре руководства по OpenAPI.
  • Для использования предварительно созданного документа в спецификации OpenAPI, можно использовать файл спецификации OpenWeatherMap или файл спецификации Sunrise/sunset API (Клик правой кнопкой мыши ссылку и сохраните файл YAML на рабочем столе.)

  Единственная папка, с которой мы будем работать в загруженном zip-архиве, — это папка dist (сокращение от дистрибутива). Все остальное используется, только если мы перекомпилируем файлы Swagger, что выходит за рамки этого руководства.

  Настройка Swagger документации для API в Golang

  В предыдущей статье мы создали RESTful API в Golang. Теперь, когда у нас есть готовый проект, надо понять, как его использовать. Ведь если нельзя протестировать проект и увидеть его возможности, он будет просто бесполезен.

  Без полноценной документации, позволяющей тестировать конечные точки и видеть возможности проекта, пользователи не будут даже пытаться его использовать. Стало быть, нужно написать документацию, но на это может уйти много времени, которое можно было бы потратить на разработку крутых функций для наших приложений. Так что же делать? Крутым функциям — крутая документация Swagger!

  Библиотеки

  Начнём создавать Swagger документацию с библиотек. Вообще-то, нужна всего одна — swag — библиотека Golang, которая преобразует аннотации кода (комментарии) в документацию Swagger Documentation 2.0. Кроме swag, нам понадобится промежуточное ПО/библиотека-оболочка для каркаса разработки веб-приложений. В swag документации присутствуют ссылки на библиотеки для поддерживаемых платформ. Здесь есть простенький вариант на net/http , которому отдаёт предпочтение большинство людей. Лично мне больше нравится GIN, его я вам и продемонстрирую. Если вы используете какую-то другую платформу — не беда, ведь аннотации одни и те же, так что всё равно почерпнёте здесь для себя что-то новое.

  Стоит упомянуть и о ещё одной библиотеке go-swagger , которая кажется намного более мощной и популярной: переключайтесь на неё, если вам нужен больший контроль над тем, что у вас генерируется. Ну а я предпочитаю библиотеку swaggo/swag из-за её простоты.

  Строка документации

  Теперь переходим к аннотациям/комментариям/строке документации или как там всё это дело называется? Короче, пояснениям перед конкретной API функцией, использующейся для генерирования Swagger документации.

  Прежде чем приступать к рассмотрению отдельных конечных точек API, нам надо составить общее описание всего нашего проекта. Эта часть аннотаций находится в пакете main , непосредственно перед функцией main :

  Примечание: все примеры взяты из моего репозитория, где можно найти запускаемое приложение вместе с пользовательским интерфейсом Swagger UI и документацией.

  Вот первый пример с общей информацией об API: имя, версия, лицензия, базовый URL и т.д. Вы можете добавить ещё несколько полей, которые приводятся вот тут вместе с примерами.

  Кроме аннотаций, надо импортировать необходимые библиотеки, в том числе blank import пакета docs , который мы будем генерировать (об этом дальше). И ещё нам нужно подключить в одной из конечных точек интерфейс Swagger UI. Здесь используем "/swagger/*any .

  Вот часть пользовательского интерфейса, создаваемого аннотациями:

  Дальше важная часть — аннотации для API функций. Аннотации стоят перед каждой функцией, зашитой в main , и при работе с конечной точкой, такой как эта v1.GET("/users/:id", apis.GetUser) , надо предварять её аннотацией. Как показано здесь:

  Это минимальный набор аннотаций, который вы должны использовать. Здесь всё интуитивно понятно. Мне хотелось бы только обратить ваше внимание на models.User , возвращаемый при успешном завершении. Это модель таблицы базы данных, которая находится в пакете models . Ссылка на неё приводит к её появлению в интерфейсе Swagger UI в разделе models:

  А это раздел для нашей конечной точки:

  Генерируем документацию!

  Здесь нам потребуется всего одна команда swag init , которую мы должны запустить из каталога с main . Для репозитория нашего макета это будет . /cmd/blueprint/ . Этой командой будет создан пакет docs с двумя версиями документации — в формате JSON и YAML.

  Имея возможность таким образом генерировать этот пакет, я всё же предпочитаю хранить его на GitHub: ведь он импортируется в пакете main , следовательно, нужен для запуска приложения. Если нет желания помещать этот сгенерированный код на GitHub, можете написать цель Makefile, которая тут же повторно сгенерирует Swagger документацию перед созданием и запуском приложения. Если всё же решите отправить его на GitHub, возможно, потребуется запускать документацию через go fmt , потому что не факт, что она будет форматирована так, «как должна быть».

  Аутентификация

  На этом этапе мы могли бы уже запустить приложение, полюбоваться новеньким интерфейсом Swagger UI и поставить точку. Не хватает лишь одного — аутентификации для API. Если сейчас оставить Swagger UI как есть, кто угодно сможет отправить запрос в любую конечную точку. А это крайне нежелательно, так как в этом случае есть опасность повреждения данных или из базы данных может произойти утечка конфиденциальной информации в Интернет. Словом, причин установить хотя бы простую аутентификацию пользователя для API и Swagger UI у нас предостаточно. Как же нам это сделать?

  Во-первых, давайте реализуем аутентификацию. В случае с GIN создаём простенькое промежуточное ПО аутентификации, которое мы подключаем к группе маршрутизаторов:

  Подключая промежуточное ПО к той или иной группе (группам), мы можем контролировать, что подлежит аутентификации, а что — нет. Например, нам не нужно, чтобы сам Swagger UI проходил аутентификацию.

  Примечание: я убрал из примеров часть кода для простоты восприятия. Весь код доступен в ветке rest-api репозитория здесь.

  Вернёмся теперь к модулю main . Здесь нам надо добавить аннотацию securityDefinitions :

  Мы прикручиваем к Swagger UI аутентификацию через API ключи в заголовке Authorization . Кроме такой аутентификации, вы можете также установить базовую аутентификацию ( securitydefinitions.basic ) с использованием имени пользователя и пароля или одну из версий OAuth2 ( securitydefinitions.oauth2 ): все варианты доступны в документации здесь. Лично я предпочитаю API-ключи за простоту и удобство.

  Чтобы Swagger понимал, что та или иная конечная точка прошла аутентификацию, к уже упомянутой API функции надо добавить аннотацию @Security :

  На этом всё. Выполнив повторную генерацию документации, запускаем наше приложение:

  В логах GIN вы должны увидеть что-то вроде этого:

  Теперь можно открыть Swagger UI на http://localhost:1234/swagger/index.html и проверить нашу документацию!

  Внимание: если эта команда не даёт результата, пробежитесь ещё раз по предыдущей статье.

  Напомним: security definition в пакете main даёт нам следующее окошко:

  При вводе неправильного API-ключа ( "wrong_api_key" ) получаем код ответа 401:

  Документирование #микросервисов

  

  Оригинальная статья является размышления на тему почему документация в мире микросервисов критично необходима и как ее можно создавать и публиковать используя swagger. Пошаговой инструкцией по настройке она точно не является.

  Вступление

  Несколько месяцев назад один из наших бекенд разработчиков интернов получил задачу — разработать новый простой сервис. Сервис должен был генерировать емайл отчеты о пользовательской активности. В задаче не было ничего сложного и у интерна все получилось. Однако через несколько недель мы захотели включить в отчет более детальную информацию о некоторых конкретных пользователях. Я решил обновить этот сервис самостоятельно. “Просто получи данные из нашего пользовательского сервиса и вставь их в емайл”, — думал тогда я.

  На это у меня ушло несколько часов, и даже пришлось подключить двоих других разработчиков только для того, чтобы найти правильные REST endpoints и необходимые мен структуры. “Никогда больше. Должен быть более правильный метод это сделать…”, — крутилось у меня в голове все это время.

  Микросервисная архитектура подразумевает набор самостоятельных сервисов, которые общаются друг с другом, а для конечного пользователя выглядит как единая программа. Один из самых популярных протоколов для обмена сообщениями между микросервисами — это REST. Проблема в том, что REST не является само описательным протоколом. Это значит, что клиент должен знать конкретную комбинацию URL, HTTP метода и формата ответа. В некоторых случаях необходимо также знать также формат тела запроса. Обычно реализация REST интерфейса базируется на общих принципах и традициях, принятых в вашей организации. В любом случае, REST endpoints всегда должны быть описаны в одном конкретном документе, доступном для всех остальных разработчиков. О том, как и где хранить, мы поговорим чуть позже, а пока давайте обсудим основы — формат документации.

  Swagger

  

  Документацию должно быть легко читать, писать, парсить, генерировать, исправлять, обновлять и прочее. Решение должно быть настолько простым, чтобы даже самые ленивые разработчики им пользовались. После небольшого исследования мы в Ataccama решили использовать Swagger для документирования наших REST APIs.

  Swagger — это фреймворк и спецификация для определения REST APIs в формате, дружественном к пользователю и компьютеру (в нашем случае JSON или YAML). Но Swagger — это не просто спецификация. Основная его мощь заключается в дополнительных инструментах. Для Swagger существует огромное количество бесплатных утилит (как официальных, так и написанных сообществом), которые могут сделать жизнь (вашу и ваших коллег) немного более счастливой. Вы можете установить все это на свои собственные сервера и посмотреть, как это работает — например, попробовать работу с браузером документов или Swagger онлайн-редактором.

  Как мы это делаем?

  Если вы тоже думаете, что Swagger — это здорово, то читайте дальше. Сейчас будет немного подробностей о том, как мы используем его в Ataccama, в таинственном мире микросервисов.

  У каждого микросервиса в определенной папке лежит файл со Swagger описанием и хранится это все прямо в git-репозитории. Описания могут быть как сгенерированы при помощи Swagger generator, так и записаны туда вручную. Прелесть заключается в том, что для записи определений используются JSON и YAML форматы. Их легко распарсить, и во время сборки проекта мы можем автоматически проверять соответствие REST endpoints и документации. Несоответствия будут генерировать предупреждения, и тем самым стимулировать разработчика поддерживать документацию в актуальном состоянии.

  Хранение документации внутри микросервиса позволяет нам отображать её в любое время прямо из этого микросервиса в процессе работы. Это помогает тестировать и отлаживать REST endpoints в процессе развертывания сервиса на собственной машине. А ещё у Swagger есть инструмент с веб интерфейсом для тестирования REST endpoints.

  Поскольку каждый микросервис предоставляет собственную документацию, мы можем настроить специальную задачу для Дженкинса (или любого другого CI сервера), которая сгенерирует полную документацию для всего проекта. Эта задача собирает Swagger файлы из всех микросервисов, производит некоторые минимальные модификации (дедупликация, удаление ненужных атрибутов) и на выходе генерирует единый Swagger файл, содержащий полную актуальную информацию для всего проекта.

  Публикация документации.

  Централизованное хранение и редактирование документации — это только первый шаг. Следующий — сделать ее доступной для всех разработчиков, тестеров и остальных заинтересованных людей в компании. И Swagger UI — это именно то, что вам для этого понадобится. При помощи небольшой JavaScript библиотеки Swagger UI генерирует HTML элементы для всех ваших REST endpoints, которые далее можно упорядочивать с помощью HTML разметки.

  

  По умолчанию Swagger UI подгружает собственный Swagger файл с примерами. Все остальные API должны быть загружены вручную. Но конфигурация занимает всего несколько секунд.

  Теперь у нас есть сгенерированная документация в читабельном виде. Время отправить её на сервер.
  Некоторое время назад мы в Ataccama начали использовать Docker, и поэтому подумали, а почему бы не упаковать всю документацию в отдельный докер контейнер, загрузить его в наш частный репозитарий, а потом задеплоить в докер кластер? Дженкинc может это сделать буквально за несколько секунд. Как результат мы всегда имеем обновленную документацию доступную к просмотру через браузер.

  Кроме того, использование докера дает нам еще несколько преимуществ:

  Каждый разработчик может просто загрузить документацию и запустить её на собственном компьютере всего одной командой.

  И это только начало.

  Это только общая идея того как мы генерируем документацию для REST endpoints и публикуем ее при помощи докера для наших микросервисов. К сожалению, синхронный REST это не все, что нам надо документировать в этом лабиринте микросервисов. В какой-то момент хочется перейти на более продвинутые системы общения, на асинхронный обмен сообщениями, очереди, подписки на события и прочее.

  Несмотря на расхваливание Swaggerа мы все еще не нашли удобного метода документирования асинхронных сообщений. По факту, в Атаккаме мы недовольны нашим текущим решением и все еще пытаемся найти что-нибудь более простое и красивое для описания очередей сообщений и их структур. Если у вас есть идеи как это можно сделать лучше, пишите в комментариях. Любые интересные идеи приветствуются.

  Автор Lubos Palisek
  Backend software developer in Ataccama. Greedy for new cloud based technologies and ideas.

  Ataccama Corporation – международная компания, производитель программного обеспечения, специализирующаяся в области решений по управлению качеством данных, управлению мастер-данными и управления данными предприятия (data governance), решениями которого уже воспользовались более 250 компаний, начиная от предприятий среднего размера и заканчивая международными компаниями из различных отраслей.

  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-реализация спецификации. Для ее использования потребуется:

  • Java 8 и выше
  • Apache Maven 3.0.4 и выше

  Для его внедрения в проект используются две зависимости. Вот примеры:

  Другой способ — настроить maven-плагин. Тогда описания при сборке проекта будут генерироваться в файл YAML. Пример:

  Для конфигурации нужны еще два бина (beans). В них мы описываем название приложения, версию API, добавляем другие важные данные. Посмотреть примеры можно в этом репозитории на GitHub . В нем представлены образцы Swagger Core из библиотеки Java. Каждый образец содержит файл Readme , в котором подробно описано, как его запускать и что проверять.

  После настройки конфигурации мы получим аннотации, которые можно использовать для документирования кода.

  Аннотация	Использование
  @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:

  • Генерирование серверов — позволяет избавиться от рутины, создавая шаблонный код на 20+ языках.
  • Упрощенное генерирование SDK — можно создавать клиентские наборы на 40+ языках для быстрой интеграции с вашим API.

  Чтобы добавить Swagger Codegen в проект, используйте зависимость:

  Как и в случае с Swagger Core, можно настроить maven-плагин для генерации клиента или мок-сервера.

  Читать:

  Android studio как изменить цвет текста