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.

Petstore

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

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

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

Authorize

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

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

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

Try it out

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

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

Execute

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

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

Response

Important: Petstore — это функционирующий API, и вы фактически создали питомца. Теперь вам нужно взять на себя ответственность за вашего питомца и начать кормить и ухаживать за ним! Шутки — шутками, но большинство пользователей не осознают, что играют с реальными данными, когда выполняют ответы в API (особенно при использовании своего собственного ключа API). Эти тестовые данные могут быть чем-то, что вам придется стереть при переходе от исследований и изучения API к использованию API для реального использования.

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

Разворачиваем точку GET /pet/
Нажимаем кнопку Try it out
Вводим ID питомца, который использовали в предыдущей операции. (Если забыли ID, посмотрите на конечную точку POST Pet, чтобы проверить значение.)
Нажимаем 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).

OpenWeatherMap

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

Подготавливаем действительный документ спецификации OpenAPI:
- Инструкции по созданию документа спецификации OpenAPI с нуля см. В обзоре руководства по OpenAPI.
- Для использования предварительно созданного документа в спецификации OpenAPI, можно использовать файл спецификации OpenWeatherMap или файл спецификации Sunrise/sunset API (Клик правой кнопкой мыши ссылку и сохраните файл YAML на рабочем столе.)
Единственная папка, с которой мы будем работать в загруженном zip-архиве, — это папка dist (сокращение от дистрибутива). Все остальное используется, только если мы перекомпилируем файлы Swagger, что выходит за рамки этого руководства.
- Извлечем папку dist из папки swagger-ui-master в другой каталог. (После этого папку swagger-ui-master и zip-файл можно удалить.)
- Перетащим файл спецификации OpenAPI (из шага 1) в папку dist. (Если вы используете предварительно созданные файлы OpenAPI, файл называется либо openapi_openweathermap.yml, либо openapi_sunrise_sunset.yml.) Ваша файловая структура должна выглядеть следующим образом:
```
 ├── dist │ ├── favicon-16x16.png │ ├── favicon-32x32.png │ ├── index.html │ ├── oauth2-redirect.html │ ├── swagger-ui-bundle.js │ ├── swagger-ui-bundle.js.map │ ├── swagger-ui-standalone-preset.js │ ├── swagger-ui-standalone-preset.js.map │ ├── swagger-ui.css │ ├── swagger-ui.css.map │ ├── swagger-ui.js │ ├── swagger-ui.js.map │ ├── swagger30.yml │ └── [your openapi specification file] 
```
```
url: "http://petstore.swagger.io/v2/swagger.json" 
```
- Меняем значение url на относительный путь к вашему файлу YAML, а затем сохраните файл. Например
```
url: "openapi_openweathermap.yml", 
```
```
url: "openapi_sunrise_sunset.yml", 
```
- Изучим файл index.html локально в браузере. Стоит обратить внимание, что ограничения безопасности Chrome (возражения CORS) не позволяют просматривать файл Swagger UI локально. Но есть несколько обходных путей:
  - Просмотр файла локально с помощью Firefox (это самый простой способ);
  - Использование размещенного в Интернете URL-адреса openapi_openweathermap.yml или openapi_sunrise_sunset.yml. (Клик правой кнопкой мыши ссылку и выберите «Копировать адрес ссылки».);
  - Загрузка папки dist на веб-сервер и просмотр ее содержимого на сервере;
  - Поместить файл YAML в общедоступный GitHub Gist и затем нажать Raw . Использовать URL для этого Gist;
  - Использовать локальный сервер, такой как simple local HTTP server.
  Когда файл Swagger UI будет готов к публикации, просто загружаем папку на веб-сервер и переходим в файл index.html. Например, если название каталога dist осталось без изменений, переходим по адресу http://myserver.com/dist/. (Имя папки dist можно менять на любое другое.)
  
  Tip: Для получения дополнительных инструкций по работе с Swagger UI см. Документацию Swagger.io.
  
  Конфигурация параметров Swagger UI
  
  Swagger UI предоставляет различные параметры конфигурации (не связанные с параметрами OpenAPI), которые можно использовать для настройки интерактивного дисплея. Например, можно указать, будет ли каждая конечная точка развернута или свернута, как будут сортироваться теги и операции, показывать ли заголовки запросов в ответе, включать ли раздел «Модели» после списка конечных точек и многое другое.
  
  В этом руководстве не будем вдаваться в подробности этих параметров конфигурации.
  
  Если посмотреть на код демонстрации пользовательского интерфейса Swagger (перейдите в View> Source), то увидим параметры, перечисленные в разделе // Build a system :
```
 // Build a system const ui = SwaggerUIBundle(< url: "openapi_openweathermap.yml", dom_id: '#swagger-ui', defaultModelsExpandDepth: -1, deepLinking: true, presets: [ SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset ], plugins: [ SwaggerUIBundle.plugins.DownloadUrl ], layout: "StandaloneLayout" >) 
```
  Все параметры (например, deepLinking , dom_id и т. Д.) являются значениями по умолчанию. Добавлен defaultModelsExpandDepth: -1 , чтобы скрыть раздел «Модели» в нижней части экрана Swagger UI.
  
  О параметрах конфигурации Swagger UI можете узнать в документации Swagger.
  
  Проблемы Swagger UI
  
  Изучая интерфейс Swagger, можно заметить несколько ограничений:
  - Не так много места для подробного описания работы конечных точек. При наличии нескольких абзацев с подробностями и сведениями о параметре, лучше всего ссылаться из описания на другую страницу в документации. Спецификация OpenAPI предоставляет способ ссылки на внешнюю документацию как в объекте paths , так и в объекте info , а также и в объекте externalDocs .
  - Интерфейс Swagger выглядит практически одинаково для каждого API. Можно настроить Swagger UI под свои собственные бренды, но понадобятся навыки UX. Относительно легко изменить цвет и изображение в верхней панели навигации.
  - Swagger UI может быть отдельным сайтом от другой документации. Это означает, что в своей документации потребуется ссылаться на Swagger в качестве ссылки для конечных точек. В разделе «Интеграция Swagger UI с остальными документами», описаны стратегии объединения справочных документов и руководства пользователя.
  Устранение неполадок
  
  При настройке Swagger UI, могут возникать проблемы. Следующие проблемы являются наиболее распространенными:
  
  Проблема CORS
  
  Если безопасность правильно настроена, но запросы отклоняются, это может быть связано с проблемой CORS (cross-origin resource sharing). CORS — это мера безопасности, которую веб-сайты внедряют, чтобы другие сценарии и процессы не могли получать свое содержимое через запросы от удаленных серверов. Подробности см. В разделе «Поддержка CORS» в документации по интерфейсу Swagger.
  
  Если запросы не работают, переходим в консоль JavaScript браузера (в Chrome, View> Developer> Javascript Console), делаем запрос, и смотрим, относится ли ошибка к запросам разных источников. Если это так, можно попросить разработчиков включить CORS на конечных точках.
  
  Проблемы с url хоста
  
  Хост тестового сервера может быть еще одной причиной отклонения запросов. Некоторые API (например, Aeris Weather) требуют, создания идентификатор приложения на основе URL-адреса хоста, на котором будут выполняться запросы. Если зарегистрированным URL-адресом хоста является http://mysite.com , но тест отправляется по адресу https://editor.swagger.io/ , сервер API отклонит запросы.
  
  Встраивание Swagger UI в существующий сайт
  
  Помимо публикации выходных данных пользовательского интерфейса Swagger в качестве отдельного сайта, можно встраивать файл Swagger в существующий сайт. Описание можно посмотреть здесь:
  - Standalone Swagger UI Demo
  - Embedded Swagger UI Demo
  Swagger UI адаптивен и хорошо масштабируется, что позволяет вписать его практически в любое пространство. Тем не менее, встроенный в существующий сайт Swagger выглядит как сайт внутри сайта.
  
  Тестирование API с помощью Swagger: особенности и преимущества
  
  API (Application Programming Interface) — это набор процедур, протоколов и инструментов, позволяющих разным программным приложениям общаться между собой. API дает возможность осуществлять взаимодействие с различными сервисами и приложениями, используя специальные запросы и ответы.
  
  Наиболее популярные и эффективные инструменты для тестирования API:
  - Postman — это инструмент для тестирования API, позволяющий создавать, отправлять и тестировать HTTP-запросы и проверять ответы на них.
  - Swagger — это инструмент для документирования и тестирования API, позволяющий автоматически создавать документацию API из описания структуры API в формате YAML или JSON файла.
  - SoapUI — это инструмент для тестирования веб-сервисов, позволяющий создавать и выполнять тесты на протоколе SOAP.
  Рекомендуем публикацию по теме
  - Как тестировать веб-сервисы с помощью SoapUI смотреть 129 мин
  - Fiddler — это инструмент для анализа и отладки HTTP-трафика между веб-браузером и веб-сервером. С точки зрения тестирования API Fiddler позволяет перехватывать, анализировать и модифицировать HTTP-запросы и ответы, передаваемые между клиентом и сервером. Это позволяет тестировщикам осуществлять валидацию запросов и ответов, проверять правильность передачи параметров, куки и другие элементы запросов, отслеживать проблемы с трафиком, а также выявлять и локализовать проблемы с API.
  - JMeter — это инструмент для тестирования производительности и функциональности программного обеспечения, который может использоваться для тестирования API. С точки зрения тестирования API, JMeter является инструментом, позволяющим создавать запросы к API, анализировать ответы и оценивать производительность и функциональность API. JMeter может использоваться для создания нагрузки на API, чтобы измерить производительность, время ответа и другие метрики, которые помогут обнаружить ошибки в API и улучшить его производительность и функциональность.
  Рекомендуем публикацию по теме
  - QA: Основы нагрузочного тестирования с инструментом Jmeter смотреть 66 мин
  Вышеперечисленные инструменты позволяют тестировщикам эффективно и быстро проверять API на разных этапах разработки, чтобы обеспечить его соответствие требованиям и качеству.
  
  В данной публикации рассмотрим подробнее Swagger, позволяющий создавать, документировать и тестировать API. С помощью Swagger можно узнать доступные эндпоинты, параметры запросов и формат ответов.
  
  О Swagger
  
  Swagger разработан компанией Reverb Technologies, основанной в 2010 году в Миннеаполисе, США. Основателями компании были Тони Тамбурино (Tony Tambourine), Райан Дювелл (Ryan Duell) и Ник Селлер (Nick Sutterer).
  
  Swagger создан в целях облегчения работы разработчиков API и обеспечения большего взаимодействия между разработчиками и потребителями API. В 2015 году Swagger был перенесен в сообщество OpenAPI Initiative, которое является частью Linux Foundation, где его разработка и поддержка продолжаются по сей день.
  
  Преимущества и особенности Swagger:
  - Легкость использования: Swagger имеет простой и легкий интерфейс, позволяющий разработчикам быстро и легко создавать и документировать API.
  - Автоматическое поколение документации: Swagger позволяет автоматически создавать документацию для API с использованием стандарта OpenAPI. Это позволяет потребителям API быстро и легко понять, как взаимодействовать с API и использовать его функциональность.
  - Поддержка различных языков программирования: Swagger поддерживает многие языки программирования, что позволяет разработчикам использовать его для документирования API на любом языке программирования.
  - Поддержка открытых стандартов: Swagger основан на стандартах OpenAPI, которые поддерживаются большим количеством инструментов и платформ, что позволяет разработчикам использовать его с любым другим инструментом или платформой, поддерживающими стандарты OpenAPI.
  - Тестирование и валидация API: Swagger позволяет разработчикам тестировать и валидировать API, обеспечивая большую надежность и качество работы API.
  - Расширяемость Swagger имеет открытый код и активное сообщество разработчиков, что позволяет им расширять и настраивать его под свои нужды.
  Для каждого из методов HTTP Swagger позволяет описать параметры запросов и формат ответов.
  
  Например, для метода GET можно описать параметры запросов, такие как query string parameters, headers, или path parameters, и формат ответа, такой как JSON или XML. Аналогично Swagger позволяет описывать параметры и формат ответов для методов POST, PUT и DELETE. Это обеспечивает понятность и консистентность описания API и позволяет разработчикам эффективно использовать API в своих приложениях.
  
  Примеры описания параметров запросов и формат ответов можно найти здесь.
  
  Примеры методов
  
  POST метод (создание объекта):
  
  Результат после отправки запроса:
  
  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:
  - API clients: ActionScript, Ada, Apex, Bash, C# (.net 2.0, 3.5 or later), C++ (cpprest, Qt5, Tizen), Clojure, Dart, Elixir, Elm, Eiffel, Erlang, Go, Groovy, Haskell (http-client, Servant), 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 (ES5, ES6, AngularJS with Google Closure Compiler annotations) 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), Typescript (Angular1.x, Angular2.x, Fetch, jQuery, Node)
  - Server stubs: 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)
  - API documentation generators: HTML, Confluence Wiki
  - Configuration files: Apache2
  - Others: JMeter
  Прочая информация, в частности инструкция по использованию, представлена здесь:
  Общая информация
  
  Заключение
  
  Это был краткий наглядный обзор для начинающих разработчиков API, целью которого было предоставить общую картину того, что такое Swagger, зачем он нужен и какие он дает основные плюсы с моей личной точки зрения.
  
  Swagger
  
  Swagger — это набор инструментов, который позволяет автоматически описывать API на основе его кода. API — интерфейс для связи между разными программными продуктами, и у каждого проекта он свой. Документация, автоматически созданная через Swagger, облегчает понимание API для компьютеров и людей.
  
  Освойте профессию
  «Fullstack-разработчик на Python»
  
  На основе кода или набора правил Swagger автоматически генерирует документацию в формате JSON-файла. Ее можно встроить на страницу сайта или в приложение, чтобы пользователи могли интерактивно знакомиться с документацией, можно отправлять клиентам — сгенерировать такое описание намного быстрее, чем написать с нуля.
  
  Swagger иногда называют фреймворком. Фреймворк — набор инструментов и правил, которым по сути является Swagger. Часть инструментов доступна бесплатно и имеет открытый исходный код, еще часть — платная и предназначена для компаний.
  
  Название читается как «Сваггер». Альтернативное название — OpenAPI. Так называется спецификация, по которой работает Swagger, но иногда название применяют при описании продукта.
  
  Профессия / 12 месяцев
  Fullstack-разработчик на Python
  
  Создавайте веб-проекты самостоятельно
  
  Кто пользуется Swagger
  - Разработчики, которые хотят быстро задокументировать API проекта и не могут тратить время на то, чтобы писать документацию с нуля.
  - Разработчики, которые собираются внедрить API стороннего программного продукта, — они пользуются документацией, в том числе созданной в Swagger.
  - Технические писатели при создании документации для проектов — в качестве основного или вспомогательного инструмента.
  Читайте также Как выбрать IT-специальность в новых реалиях?
  
  Для чего нужен Swagger
  
  Документация API. Основное назначение Swagger — автоматически генерировать документацию, понятную для людей и для машин. Соответственно, чаще всего он применяется, чтобы быстро и легко документировать код API. Обычно используется в связке с архитектурой RESTful API.
  
  Разработка API. Swagger используется, когда, например, разработчику нужно свериться с документацией при доработке продукта, или он хочет сгенерировать ее из кода. Иногда требуется обратный процесс — генерация кода на основе документации, возможная благодаря компоненту Swagger Codegen. Мы поговорим о нем ниже.
  
  Взаимодействие с API. Возможность генерации кода используется при взаимодействии с API других проектов. Swagger Codegen может генерировать код для конечного клиента, который будет работать с API, — это удобно, когда стоит задача сэкономить время.
  
  Два способа создания документации
  
  На основе кода. Инструмент «читает» код API и на его основе генерирует документацию. Такой способ считается более простым, потому что от разработчика не требуется знать спецификацию и писать что-то помимо самого кода. Но его рекомендуют применять только тогда, когда документация нужна срочно, — потому что второй способ позволяет создавать более подробные и понятные описания.
  
  На основе спецификации. Второй способ — использовать спецификацию Swagger, которая называется OpenAPI. Он сложнее, потому что необходимо знать язык формальных правил — на нем нужно описать сущности кода, чтобы инструмент понял написанное и сгенерировал документ. Но этот подход более правильный, потому что такая документация более понятна и человекочитаема. Писать необходимо с помощью форматов JSON или YAML либо в специальном редакторе Swagger Editor — о нем мы подробнее расскажем ниже.
  
  Станьте Java-разработчиком
  и создавайте сложные сервисы
  на востребованном языке
  
  Что такое спецификация Swagger
  
  Swagger работает на основе спецификации OpenAPI 3.0. Раньше она тоже называлась Swagger, но ее переименовали в 2015 году, когда проект передали другой команде разработчиков.
  
  Спецификация — набор правил, которые описывают, как должна выглядеть и работать та или иная технология. Это теоретический «каркас» для будущего программного проекта. На его основе пишется код, реализация, которая работает по описанной в спецификации логике. Соответственно, OpenAPI — это набор правил и стандартов для описания API.
  
  Работа происходит так: специалист описывает код с помощью формальных текстовых правил. Swagger «понимает» написанное и на его основе создает человекопонятную интерактивную документацию.
  
  Как устроена спецификация
  
  В спецификации есть основные сущности, каждая из которых включает в себя более мелкие. С их помощью происходит описание документации. Синтаксис примерно такой:
  
  Объект может представлять собой, например, имя пользователя, название модуля, ссылку или что-то еще. Основных объектов восемь; остальные вложены в них:
  - openapi. Его значение — версия OpenAPI, которая используется в проекте;
  - info. Включает в себя вложенные объекты, которые содержат основную информацию об API: название, описание, лицензию, контакты разработчиков и т.д.;
  - servers. Включает в себя ссылки, ведущие к серверам, — базовые пути для доступа извне без учета конечных точек;
  - paths. Описывает конечные точки, или эндпоинты (end points) — конец пути к той или иной сущности. Для каждого эндпоинта прописываются запросы GET, POST, DELETE и PUT — операции для взаимодействия с сущностью;
  - components. В нем хранятся схемы, которые могут использоваться в разных местах документации. Например, можно создать схему «Пользователь» с полями «Имя», «Адрес» и другими. После описания в components схему можно использовать дальше в коде документации;
  - tags. Хранит метаданные тегов: заголовок, описание и так далее. Помогает более подробно описывать происходящее;
  - security. Описывает методы для обеспечения безопасности, которые можно использовать с API;
  - externalDocs. Содержит ссылки на внешнюю документацию, обычно с дополнительной информацией. Например, это может быть документация какого-то стороннего инструмента, который используется в коде.
  4 компонента Swagger
  
  Swagger можно разделить на четыре основных компонента. Есть и другие, которые относятся к коммерческой версии, но о них говорят реже и используют не так часто.
  
  Swagger Core. Это ядро Swagger — программная реализация спецификации OpenAPI 3.0. Выше мы говорили, что на основе спецификации пишется код, который реализует описанную в ней логику. В случае со Swagger это и есть Core.
  
  Swagger Core написан на языке Java, поэтому для его корректной работы понадобится Java не старше версии 8.0. Также нужны будут фреймворк Apache Maven 3.0.3 или новее и JSON-процессор Jackson 2.4.5 или новее.
  
  После установки в проект Swagger Core позволит автоматически генерировать документацию на основе кода при сборке проекта. Правила генерации описываются с помощью специальных команд — аннотаций: они размещаются в коде и показывают, что именно представляет собой та или иная его часть. Это один из минусов способа генерации на основе кода — он становится очень массивным и громоздким из-за обилия аннотаций.
  
  Станьте веб-разработчиком и найдите стабильную работу на удаленке
  
  Swagger UI. UI расшифровывается как user interface, графический интерфейс. Этот компонент делает работу со Swagger нагляднее и понятнее: он визуализирует документацию, представляет ее в более простом для понимания виде. Более того, она становится не просто визуальной, но интерактивной, с ней можно взаимодействовать — без написания кода, просто с помощью интерфейса.
  
  С помощью Swagger UI можно создавать и отправлять запросы разных типов, можно быстро перемещаться по документации и тестировать проект. Визуальный интерфейс можно встроить в приложение или разместить на странице, его поддерживают все браузеры — поэтому им пользуются в том числе для того, чтобы разъяснять пользователям и клиентам особенности взаимодействия с API.
  
  Swagger Codegen. Мы уже упоминали этот компонент выше — он может генерировать код на основе правил. Автоматически сгенерированный код решает только шаблонные задачи, так что Codegen не заменяет программиста, но серьезно облегчает ему задачу. Он позволяет избавиться от части рутины.
  
  Swagger Codegen генерирует:
  - заглушки серверов (server stub) — своеобразные «точки входа» для внешних объектов. Те обмениваются данными с заглушками и таким образом общаются с сервером;
  - клиентские библиотеки API (API clients) — SDK, то есть наборы инструментов для разработчика, в нашем случае для работы с API на стороне клиента;
  - документацию на основе имеющегося кода проекта.
  Компонент поддерживает множество языков: Java и ряд фреймворков для него, C++ и C#, Kotlin, Node.js, Scala, Haskell. Для генерации клиентских библиотек API также поддерживаются Groovy и Bash, а для заглушек серверов — PHP, Python, Ruby и Rust. Генератор документации поддерживает HTML и Confluence — вики-проект для внутренних баз знаний.
  
  Swagger Editor. Это редактор спецификаций: он позволяет просматривать написанные правила, изменять и дополнять их. Существуют онлайн-версия редактора и версия для скачивания. Выглядит он как разделенное на две части окно: слева по спецификации пишется код описания API, справа генерируется визуальный интерфейс Swagger UI. Интерфейс одновременно интерактивен и функционален: можно, не выходя из редактора, посмотреть, как будет выглядеть документация. Там же можно протестировать ее и сразу внести изменения.
  
  Редактор автоматически проверяет то, что пользователь написал в левой части, и указывает на ошибки в использовании спецификации. Если они есть, это покажется в режиме реального времени.
  
  Плюсы использования Swagger
  - Swagger упрощает и ускоряет написание документации, экономит время разработчиков и технических писателей.
  - Можно сократить рутинную работу и предоставить создание шаблонного кода Swagger Codegen: это опять же экономит время.
  - Документация получается подробной и ясной для всех категорий читателей: технических специалистов, обычных пользователей и роботов.
  - Пользоваться Swagger можно довольно гибко: создавать документацию на основе кода или самостоятельно, применять возможности визуального интерфейса для тестирования и быстрой навигации.
  - Документацию, написанную с помощью Swagger, можно легко встроить в страницу сайта или в приложение, и она будет интерактивной и полностью функциональной. Но лучше все же сверстать свой вариант отображения — стандартный интерфейс не слишком хорошо вписывается в дизайны реальных сайтов.
  Минусы Swagger
  
  Некоторые разработчики не любят Swagger, считают его бесполезным или избыточным, только усложняющим работу с API. Есть мнение, что он делает менее наглядной коммуникацию между бэкендерами, отвечающими за серверную часть, и фронтендерами, создающими клиентский интерфейс. Такое действительно возможно: Swagger генерирует большое количество кода, и одной части команды разработчиков кажется, будто этого достаточно, тогда как другой тяжело в этом разобраться. Документация не получается наглядной, и это проблема.
  
  Вторая причина, по которой Swagger критикуют, — отсутствие подробной разметки. Для создания документации многие используют такие инструменты, как Markdown. Они позволяют выделять смысловые части, создавать сноски на разные части документа, добавлять якорные ссылки. В Swagger таких возможностей нет. Ведь созданная с ним документация «изнутри» представляет собой JSON-файл, а этот формат в принципе не подразумевает средств выделения текста.
  
  Как начать работать со Swagger
  
  Редактором Swagger можно пользоваться онлайн. Также можно скачать его: все бесплатные компоненты проекта доступны на GitHub и на официальном сайте. Для корректной работы понадобится Java и несколько фреймворков — мы описали технологии выше.
  
  Есть проект SwaggerHub, облачная платформа, которая позволяет использовать возможности Swagger онлайн. Для доступа к ней предлагается три тарифных плана. План Free — бесплатный; платные планы Teams и Enterprise предназначены для компаний. Так что начинающий разработчик может пользоваться проектом и не платить за него.
  
  Подробнее узнать про инструменты создания документации и познакомиться с правилами коммерческой разработки вы можете на курсах.
  
  Fullstack-разработчик на Python
  
  Fullstack-разработчики могут в одиночку сделать IT-проект от архитектуры до интерфейса. Их навыки востребованы у работодателей, особенно в стартапах. Научитесь программировать на Python и JavaScript и создавайте сервисы с нуля.
  
  Статьи по теме:
  Похожие публикации: