209 lines
27 KiB
Markdown
209 lines
27 KiB
Markdown
---
|
||
title: "Что такое Swagger: инструмент для подготовки документации к API и проведения тестов API — журнал «Код»"
|
||
source: https://thecode.media/chto-takoe-swagger-i-kak-on-oblegchaet-rabotu-s-api/
|
||
author:
|
||
published: 2024-11-20
|
||
created: 2025-08-24
|
||
description: Swagger — инструмент, который умеет автоматически создавать описание для каждого ресурса в REST API, показывать доступные методы, параметры запроса и ответы.
|
||
tags:
|
||
- clippings
|
||
- "#swagger"
|
||
---
|
||
Мы уже рассказывали, что такое [API](https://thecode.media/api/), но на всякий случай напомним: это то, что может делать приложение по просьбе других приложений. Чтобы функциями API могли пользоваться другие люди, они должны знать, какие запросы можно отправлять, что нужно передавать в ответах и что вернётся. Всю эту информацию разработчики API указывают в документации. Но обычно вручную делать такие описания долго, особенно если API большой и функциональный, поэтому разработчики используют специальные инструменты для создания документации. Один из них — Swagger — мы сегодня и разберём.
|
||
|
||
## Что такое Swagger и как он связан с REST API
|
||
|
||
API — это набор команд, которые разработчики добавляют в приложение, чтобы другие программы могли с этим приложением взаимодействовать. Допустим, есть [сервис](https://github.com/alexwohlbruck/cat-facts) для получения фактов о кошках, и нужно, чтобы другие приложения тоже могли запрашивать эти факты. Для этого используется API, который задаёт правила для взаимодействия. С помощью запросов к этому API можно получить случайные факты о кошках.
|
||
|
||
Есть несколько подходов к созданию API. Один из самых популярных — архитектура REST API (Representational State Transfer). Она описывает, как должен быть устроен API, чтобы с ним всем было удобно работать.
|
||
|
||
В этой архитектуре каждый объект или ресурс в приложении («пользователи», «факты», «задачи») имеет свой уникальный URL, который называется эндпоинтом. Эндпоинт — это адрес, по которому отправляется запрос к API, и для работы с ним используются стандартные HTTP-методы: GET для получения данных или POST — для создания новых данных. REST API работает по принципу «без сохранения состояния» — то есть каждый запрос обрабатывается как самостоятельное действие, не зависящее от предыдущих запросов.
|
||
|
||
Чтобы объяснить другим принцип работы своего API, разработчики пишут документацию. Там они описывают, какие действия поддерживает API, как отправлять запросы, какие данные можно получить в ответ и так далее. Получается что-то вроде этого:
|
||
|
||
|
||
|
||
Что такое Swagger и как он облегчает работу с API
|
||
|
||
Пример документации API для приложения Cat Facts: указан основной URL, эндпоинты и модели данных
|
||
|
||
Чтобы упростить себе жизнь, разработчики используют разные инструменты, которые помогают создавать документацию. Один из них — [Swagger](https://swagger.io/). Он умеет автоматически создавать описание для каждого ресурса в REST API, показывать доступные методы, параметры запроса и ответы, поскольку заточен под REST API и работает с теми же стандартами URL и HTTP-методов.
|
||
|
||
Swagger берёт все ресурсы, методы и параметры, заданные в API, и превращает их в наглядное описание. В результате мы можем увидеть, какие запросы поддерживаются, какие данные нужно передавать и что возвращается в ответ. Документация, которую создаёт Swagger, будет выглядеть так:
|
||
|
||
|
||
|
||
Что такое Swagger и как он облегчает работу с API
|
||
|
||
Пользователь сразу видит структуру API. Можно раскрыть запрос и протестировать его выполнение прямо в браузере:
|
||
|
||
|
||
|
||
Что такое Swagger и как он облегчает работу с API
|
||
|
||
## Для чего используется Swagger
|
||
|
||
Мощь Swagger — в его интерактивности. Инструмент создаёт документацию, где каждый запрос, параметры и ответ можно сразу протестировать. Это позволяет быстро проверить, как работает каждый метод, и если нужно, то сразу сделать отладку.
|
||
|
||
Swagger стал настолько популярным, что сейчас разные разработчики и компании воспринимают его как стандартный инструмент для работы с API. Его используют для создания и документирования API как для внутренних целей, так и для внешних клиентов.
|
||
|
||
Инструмент могут использовать разные специалисты, которые работают с API: разработчики, системные аналитики, тестировщики, а также проектные и продуктовые менеджеры. В зависимости от роли и задач использование будет разным.
|
||
|
||
Теперь разберём подробнее.
|
||
|
||
### ➡️ Как используют Swagger разработчики API
|
||
|
||
**Создают и поддерживают документацию.** Это обязательный этап при проектировании API, особенно если он будет использоваться другими командами или клиентами. В Swagger разработчик может описать каждый эндпоинт, добавить методы, параметры и возможные ответы.
|
||
|
||
**Тестируют API.** Можно выбрать эндпоинт, задать параметры и отправить запрос, чтобы увидеть, как API обрабатывает данные. Это позволяет сразу проверить, правильно ли работает каждый метод. Swagger показывает, какой ответ приходит от API — формат JSON и коды ошибок.
|
||
|
||
**Генерируют клиентский код для API.** Если API нужно подключить к приложению, Swagger Codegen позволяет создать клиентский код для работы с этим API на более чем 40 языках программирования. Swagger также может создавать серверные заглушки, которые представляют API, но без фактической бизнес-логики. Это позволяет начать разработку клиентской части параллельно с серверной, так как клиент может тестировать API, даже если сервер ещё не готов.
|
||
|
||
**Синхронизируют работу в команде.** Swagger помогает командам избегать путаницы при разработке API и иметь доступ к актуальной документации. Если один разработчик добавляет новый эндпоинт, это сразу же видно всем, кто работает с этим API. Клиентская и серверная команды могут одновременно тестировать API и проверять, что все методы и параметры работают как нужно.
|
||
|
||
В общем, если нужно создавать с нуля свой API, то Swagger точно пригодится.
|
||
|
||
### ➡️ Как используют Swagger системные аналитики
|
||
|
||
У аналитиков всё несколько по-другому: их задача не столько в написании кода, сколько в анализе и координации работы API, а также в проверке соответствия требованиям. Вот что они делают.
|
||
|
||
**Анализируют текущее состояние API.** Swagger позволяет изучить структуру API и понять, какие данные он обрабатывает и какие функции поддерживает. Это помогает на этапе планирования: можно оценить, насколько API соответствует целям проекта, и сразу увидеть, какие ресурсы и методы уже реализованы, а какие нужно добавить.
|
||
|
||
**Взаимодействуют с разработчиками и заказчиками.** Документацию Swagger удобно демонстрировать заказчикам: используя Swagger, аналитики могут показать, какие возможности есть у API, и объяснить его работу простыми словами, не вдаваясь в технические аспекты.
|
||
|
||
**Проверяют соответствие API требованиям.** Аналитики проверяют, что каждый метод, ресурс и параметр соответствует установленным задачам. Если API меняется, аналитик может сразу увидеть, соответствует ли новое решение изначальным ожиданиям, и вовремя внести корректировки и передать задачи команде разработки.
|
||
|
||
Вам может быть интересно:
|
||
|
||
[ Что такое API](https://thecode.media/chto-takoe-api/) [ Что такое вебхук](https://thecode.media/webhook/) [ Космическая Python-программа: следим за МКС](https://thecode.media/kosmicheskaya-python-programma-sledim-za-mks/) [ Делаем HTTP-запросы на Python с библиотеками requests, aiohttp и httpx](https://thecode.media/delaem-http-zaprosy-na-python-s-bibliotekami-requests-aiohttp-i-httpx/)
|
||
|
||
## Компоненты Swagger
|
||
|
||
В Swagger есть два вида компонентов: компоненты-инструменты и компоненты спецификации.
|
||
|
||
Разные инструменты решают разные задачи. Допустим, если нужно только создать документацию, достаточно Swagger Editor, а если надо ещё и полноценно протестировать разные сценарии использования — то Swagger UI. Инструменты доступны через официальный сайт [https://swagger.io/](https://swagger.io/)
|
||
|
||
|
||
|
||
Что такое Swagger и как он облегчает работу с API
|
||
|
||
Разберём три основных.
|
||
|
||
- [**Swagger Editor**](https://editor.swagger.io/)**:** позволяет писать документацию, проектировать и описывать новые API, а также редактировать существующие. Инструмент работает в браузере, визуально отображает документацию и подсвечивает ошибки. Можно сделать базовое тестирование запросов. Также можно установить и запустить локально.
|
||
- [**Swagger UI**](https://swagger.io/tools/swagger-ui/)**:** настраиваемый инструмент, который визуализирует документацию для API. Подключается к API и позволяет взаимодействовать с ним прямо в браузере. С его помощью можно изучить структуру API и полноценно протестировать его, задавая параметры и отправляя запросы в режиме реального времени.
|
||
- [**Swagger Codegen**](https://github.com/swagger-api/swagger-codegen)**:** создаёт готовый клиентский код для работы с уже описанным API. Если у вас есть документация, созданная вручную или с помощью Swagger UI, то Swagger Codegen может использовать эту документацию для автоматической генерации клиентских библиотек на разных языках. Codegen можно сразу подключить к проекту и использовать его как модуль для работы с API.
|
||
|
||
Компоненты спецификации — это то, из чего состоит документация API. Это разделы, которые организуют и структурируют описание:
|
||
|
||
Такая структура называется спецификацией OpenAPI:
|
||
|
||
|
||
|
||
Что такое Swagger и как он облегчает работу с API
|
||
|
||
Когда в документации мы выносим общие описания в отдельные компоненты, это сокращает код. Получается, что, описав один раз параметры или ответы, можно использовать их в разных местах. Если нужно что-то изменить, достаточно обновить компонент один раз, и изменения сразу отразятся во всех запросах, где он используется.
|
||
|
||
## Как начать работать со Swagger
|
||
|
||
Самый простой способ — использовать [онлайн-версию](https://editor.swagger.io/) Swagger Editor. При запуске редактор автоматически загружает пример API — шаблон в формате YAML, разбитый на компоненты. В формате YAML используются отступы и структура с вложенностью, а не скобки или кавычки, поэтому он выглядит более простым для восприятия — сразу понятно, что к чему относится.
|
||
|
||
Можно использовать его как основу, удаляя ненужные компоненты и добавляя свои данные. Swagger Editor сразу покажет, как будет выглядеть документация на основе описания.
|
||
|
||
|
||
|
||
Шаблон OpenAPI по умолчанию
|
||
|
||
Если есть файл документации в формате OpenAPI (файл с расширением.yaml или.json), его можно загрузить в редактор. Для этого нажимаем на вкладку File, выбираем Import File и загружаем файл со своего компьютера:
|
||
|
||
|
||
|
||
Что такое Swagger и как он облегчает работу с API
|
||
|
||
Если мы сделаем ошибку в структуре или синтаксисе файла, то инструмент подсветит её и даст рекомендации по исправлению. Например, есть убрать какое-то обязательное поле в документации (в примере ниже — `version`), то Swagger Editor укажет нам на ошибку в структуре:
|
||
|
||
|
||
|
||
Что такое Swagger и как он облегчает работу с API
|
||
|
||
Если хотите работать локально, скачайте Swagger Editor с [GitHub](https://github.com/swagger-api/swagger-editor) и запустите его на своём компьютере.
|
||
|
||
Чтобы генерировать документацию из проекта, понадобится Swagger UI. Он умеет создавать спецификации OpenAPI, читая аннотации исходного кода API. Чтобы его установить, нужно скачать Swagger UI с GitHub. Для этого переходим на [GitHub Swagger UI](https://github.com/swagger-api/swagger-ui) и скачиваем репозиторий. Дальше в зависимости от того, на каком языке написан проект, можно либо подключить Swagger UI через фреймворк ([Flask-RESTX](https://flask-restx.readthedocs.io/en/latest/) для Python, [Springfox](https://springfox.github.io/springfox/) для Java), либо использовать Swagger UI как статическое веб-приложение и подключить к нему файл спецификации OpenAPI нашего API.
|
||
|
||
Дальше разберём более подробно, как это работает, на примере Python-проекта.
|
||
|
||
## Методы создания документации
|
||
|
||
Документацию в Swagger можно создавать двумя способами: вручную и через генератор.
|
||
|
||
Вручную документация пишется в [Swagger Editor](https://swagger.io/tools/swagger-editor/). Там мы подробно описываем весь наш API в компонентах OpenAPI: какие в нём есть команды, какие данные можно передавать, что API вернёт в ответ.
|
||
|
||
Второй способ — это генерация через [Swagger UI](https://github.com/swagger-api/swagger-ui). В исходном коде API разработчики добавляют специальные аннотации, которые описывают функции API: какие команды доступны, какие параметры принимают и что возвращают. Для создания таких аннотаций обычно подключают сторонние библиотеки.
|
||
|
||
Допустим, у нас есть Python-код какого-то API, который мы хотим задокументировать. В свой проект мы подключаем библиотеку Flask и расширение для аннотирования flask\_restx, чтобы с помощью аннотации `@api.doc` добавить описание для каждого метода. Swagger UI прочитает все аннотации и автоматически отобразит документацию по ним.
|
||
|
||
Сначала добавляем Flask и расширение Flask-RESTX, которые позволят дальше работать со Swagger. Открываем терминал и пишем команду:
|
||
|
||
```markup
|
||
pip install flask flask-restx
|
||
```
|
||
|
||
Теперь возьмём код нашего API и аннотируем метод:
|
||
|
||
```python
|
||
# Импортируем Flask для создания веб-приложения
|
||
from flask import Flask, request, jsonify
|
||
# Импортируем Api и Resource из flask_restx для создания и документирования API
|
||
from flask_restx import Api, Resource
|
||
# Создаём экземпляр приложения Flask
|
||
app = Flask(__name__)
|
||
# Создаём объект API с названием и описанием
|
||
api = Api(app, title="Главред API", description="API для проверки текста")
|
||
# Определяем маршрут /check для обработки запросов по этому URL
|
||
@api.route('/check')
|
||
# Создаём класс TextCheck, который наследует Resource
|
||
class TextCheck(Resource):
|
||
# Аннотация для Swagger с описанием, что делает этот метод
|
||
@api.doc(description="Проверка текста на стилистические ошибки")
|
||
# Определяем метод POST для маршрута /check
|
||
def post(self):
|
||
# Логика проверки текста
|
||
return jsonify({"result": "Текст проверен"})
|
||
# Проверяем, запущен ли этот файл напрямую
|
||
if __name__ == '__main__':
|
||
# Запускаем приложение Flask с включённым режимом отладки (debug)
|
||
app.run(debug=True)
|
||
```
|
||
|
||
Здесь мы создаём маршрут /check и добавляем к нему аннотацию `@api.doc`, которая автоматически включит описание этого маршрута в Swagger-документацию.
|
||
|
||
После этого запускаем наше приложение командой `python имя_файла.py`.
|
||
|
||
Чтобы увидеть документацию, нужно открыть приложение в браузере: его адрес будет в командной строке при запуске. В браузере увидим интерфейс Swagger и метод, который он нашёл в нашем коде. Там же можно просмотреть и протестировать API:
|
||
|
||
|
||
|
||
Что такое Swagger и как он облегчает работу с API
|
||
|
||
## Преимущества и недостатки Swagger
|
||
|
||
Swagger хорошо подходит для создания понятной документации к API, особенно если нужно, чтобы ею могли пользоваться не только разработчики, но и менеджеры или клиенты.
|
||
|
||
**Преимущества Swagger**
|
||
|
||
- Удобный интерфейс: Swagger UI показывает API в структурированном виде — сразу понятно, что к чему.
|
||
- Понятность: Swagger-документация понятна не только разработчикам, но и не техническим специалистам.
|
||
- Интерактивность: с помощью Swagger UI можно тестировать API прямо в документации, отправляя запросы и проверяя ответы.
|
||
- Просто редактировать: документация создаётся в форматах JSON и YAML, которые удобно читать и редактировать.
|
||
- Автоматизация процессов: Swagger помогает автоматизировать документирование, тестирование и поддержку API.
|
||
|
||
**Недостатки Swagger**
|
||
|
||
- Ограничения для сложных API: Swagger лучше всего подходит для простых REST API, но может ограничивать гибкость для более сложных сценариев.
|
||
- Не подходит для других архитектур: Swagger предназначен для REST API и не работает с gRPC или GraphQL.
|
||
- Громоздкие файлы: для больших API файлы спецификации могут быть громоздкими и трудными в поддержке.
|
||
- Порог входа: требует времени на изучение.
|
||
- Ограничения OpenAPI: ограничен функциями, поддерживаемыми стандартом OpenAPI, что не всегда удобно для специфичных требований.
|
||
|
||
## Аналоги Swagger
|
||
|
||
Если Swagger кажется сложным, или наоборот, его функций недостаточно, то можно рассмотреть другие подобные инструменты. |