Мы уже рассказывали, что такое API, но на всякий случай напомним: это то, что может делать приложение по просьбе других приложений. Чтобы функциями API могли пользоваться другие люди, они должны знать, какие запросы можно отправлять, что нужно передавать в ответах и что вернётся. Всю эту информацию разработчики API указывают в документации. Но обычно вручную делать такие описания долго, особенно если API большой и функциональный, поэтому разработчики используют специальные инструменты для создания документации. Один из них — Swagger — мы сегодня и разберём.
Что такое Swagger и как он связан с REST API
API — это набор команд, которые разработчики добавляют в приложение, чтобы другие программы могли с этим приложением взаимодействовать. Допустим, есть сервис для получения фактов о кошках, и нужно, чтобы другие приложения тоже могли запрашивать эти факты. Для этого используется API, который задаёт правила для взаимодействия. С помощью запросов к этому API можно получить случайные факты о кошках.
Есть несколько подходов к созданию API. Один из самых популярных — архитектура REST API (Representational State Transfer). Она описывает, как должен быть устроен API, чтобы с ним всем было удобно работать.
В этой архитектуре каждый объект или ресурс в приложении («пользователи», «факты», «задачи») имеет свой уникальный URL, который называется эндпоинтом. Эндпоинт — это адрес, по которому отправляется запрос к API, и для работы с ним используются стандартные HTTP-методы: GET для получения данных или POST — для создания новых данных. REST API работает по принципу «без сохранения состояния» — то есть каждый запрос обрабатывается как самостоятельное действие, не зависящее от предыдущих запросов.
Чтобы объяснить другим принцип работы своего API, разработчики пишут документацию. Там они описывают, какие действия поддерживает API, как отправлять запросы, какие данные можно получить в ответ и так далее. Получается что-то вроде этого:
Пример документации API для приложения Cat Facts: указан основной URL, эндпоинты и модели данных
Чтобы упростить себе жизнь, разработчики используют разные инструменты, которые помогают создавать документацию. Один из них — Swagger. Он умеет автоматически создавать описание для каждого ресурса в REST API, показывать доступные методы, параметры запроса и ответы, поскольку заточен под REST API и работает с теми же стандартами URL и HTTP-методов.
Swagger берёт все ресурсы, методы и параметры, заданные в 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 меняется, аналитик может сразу увидеть, соответствует ли новое решение изначальным ожиданиям, и вовремя внести корректировки и передать задачи команде разработки.
Компоненты Swagger
В Swagger есть два вида компонентов: компоненты-инструменты и компоненты спецификации.
Разные инструменты решают разные задачи. Допустим, если нужно только создать документацию, достаточно Swagger Editor, а если надо ещё и полноценно протестировать разные сценарии использования — то Swagger UI. Инструменты доступны через официальный сайт https://swagger.io/
Разберём три основных.
- Swagger Editor: позволяет писать документацию, проектировать и описывать новые API, а также редактировать существующие. Инструмент работает в браузере, визуально отображает документацию и подсвечивает ошибки. Можно сделать базовое тестирование запросов. Также можно установить и запустить локально.
- Swagger UI: настраиваемый инструмент, который визуализирует документацию для API. Подключается к API и позволяет взаимодействовать с ним прямо в браузере. С его помощью можно изучить структуру API и полноценно протестировать его, задавая параметры и отправляя запросы в режиме реального времени.
- Swagger Codegen: создаёт готовый клиентский код для работы с уже описанным API. Если у вас есть документация, созданная вручную или с помощью Swagger UI, то Swagger Codegen может использовать эту документацию для автоматической генерации клиентских библиотек на разных языках. Codegen можно сразу подключить к проекту и использовать его как модуль для работы с API.
Компоненты спецификации — это то, из чего состоит документация API. Это разделы, которые организуют и структурируют описание:
- schemas — описывает структуры данных (в формате JSON Schema), которые используются в запросах и ответах;
- responses — определяет возможные ответы API (коды ошибок и успешных запросов);
- parameters — описывает параметры запросов — query-параметры или path-параметры;
- examples — содержит примеры данных, которые показывают, как API должен работать;
- requestBodies — описывает тела запросов, которые передаются в POST и других методах;
- headers — определяет заголовки запросов и ответов;
- securitySchemes — задаёт схему безопасности (использование API ключей или токенов для авторизации).
Такая структура называется спецификацией OpenAPI:
Когда в документации мы выносим общие описания в отдельные компоненты, это сокращает код. Получается, что, описав один раз параметры или ответы, можно использовать их в разных местах. Если нужно что-то изменить, достаточно обновить компонент один раз, и изменения сразу отразятся во всех запросах, где он используется.
Как начать работать со Swagger
Самый простой способ — использовать онлайн-версию Swagger Editor. При запуске редактор автоматически загружает пример API — шаблон в формате YAML, разбитый на компоненты. В формате YAML используются отступы и структура с вложенностью, а не скобки или кавычки, поэтому он выглядит более простым для восприятия — сразу понятно, что к чему относится.
Можно использовать его как основу, удаляя ненужные компоненты и добавляя свои данные. Swagger Editor сразу покажет, как будет выглядеть документация на основе описания.
Если есть файл документации в формате OpenAPI (файл с расширением .yaml или .json), его можно загрузить в редактор. Для этого нажимаем на вкладку File, выбираем Import File и загружаем файл со своего компьютера:
Если мы сделаем ошибку в структуре или синтаксисе файла, то инструмент подсветит её и даст рекомендации по исправлению. Например, есть убрать какое-то обязательное поле в документации (в примере ниже — version), то Swagger Editor укажет нам на ошибку в структуре:
Если хотите работать локально, скачайте Swagger Editor с GitHub и запустите его на своём компьютере.
Чтобы генерировать документацию из проекта, понадобится Swagger UI. Он умеет создавать спецификации OpenAPI, читая аннотации исходного кода API. Чтобы его установить, нужно скачать Swagger UI с GitHub. Для этого переходим на GitHub Swagger UI и скачиваем репозиторий. Дальше в зависимости от того, на каком языке написан проект, можно либо подключить Swagger UI через фреймворк (Flask-RESTX для Python, Springfox для Java), либо использовать Swagger UI как статическое веб-приложение и подключить к нему файл спецификации OpenAPI нашего API.
Дальше разберём более подробно, как это работает, на примере Python-проекта.
Методы создания документации
Документацию в Swagger можно создавать двумя способами: вручную и через генератор.
Вручную документация пишется в Swagger Editor. Там мы подробно описываем весь наш API в компонентах OpenAPI: какие в нём есть команды, какие данные можно передавать, что API вернёт в ответ.
Второй способ — это генерация через Swagger UI. В исходном коде API разработчики добавляют специальные аннотации, которые описывают функции API: какие команды доступны, какие параметры принимают и что возвращают. Для создания таких аннотаций обычно подключают сторонние библиотеки.
Допустим, у нас есть Python-код какого-то API, который мы хотим задокументировать. В свой проект мы подключаем библиотеку Flask и расширение для аннотирования flask_restx, чтобы с помощью аннотации @api.doc добавить описание для каждого метода. Swagger UI прочитает все аннотации и автоматически отобразит документацию по ним.
Сначала добавляем Flask и расширение Flask-RESTX, которые позволят дальше работать со Swagger. Открываем терминал и пишем команду:
pip install flask flask-restx
Теперь возьмём код нашего API и аннотируем метод:
# Импортируем 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
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 кажется сложным, или наоборот, его функций недостаточно, то можно рассмотреть другие подобные инструменты.
- Apidog: относительно простой инструмент для создания документации и тестирования API. Интерфейс интуитивно понятен, поэтому новичкам будет проще разобраться.
- Postman: обычно используется для тестирования API, но и для хранения документации тоже подойдёт. Там можно создавать и хранить документацию в виде коллекций запросов. Простой для освоения, особенно если уже умеете тестировать API.
- Apigee: более сложный инструмент, предназначенный для больших проектов API. Предоставляет функции мониторинга, аналитики и безопасности.
- Redoc: подойдёт, если у вас уже есть спецификация OpenAPI. Не предоставляет возможностей для тестирования API, как Swagger UI или Postman.
