Перейти к основному содержимому

Документирование REST API с помощью Swagger и OpenAPI

Как известно, REST не является стандартом, а лишь предоставляет набор принципов, поэтому выбор способа документирования API в REST может быть разным.

OpenAPI (сайт) — это самая популярная спецификация для документирования REST API. Спецификация OpenAPI не зависит от языка программирования и является машинночитаемой. Она описывается в формате JSON или YAML и содержит подробное описание методов, параметров, структуры данных и другой информации, необходимой для взаимодействия с API.

Разрабатывать документацию по OpenAPI помогает Swagger (сайт), который представляет собой набор инструментов:

  • Swagger Codegen — для генерации кода клиента по существующей документации (полезно для заглушек).
  • Swagger UI — интерфейс, который представляет документацию. Он читает файл спецификации API и отрисовывает веб-страницу с интерактивной документацией. Даёт возможность просмотреть, какие типы запросов есть, описание моделей и их типов данных.
  • Swagger Editor — позволяет писать документацию в YAML или JSON формате.

Способы документирования по OpenAPI​

Существует два подхода к проектированию API и его документированию:

Code first​

Сначала пишем код, потом по нему генерируем документацию. Для всех популярных языков программирования есть библиотеки и фреймворки, которые с помощью специальных аннотаций/комментариев в коде могут автоматически генерировать спецификацию по OpenAPI.

Contract first​

Сначала создаем документацию (контракт), а уже потом по нему пишем код. Так как кода ещё нет, придётся вручную описывать файл спецификации OpenAPI в формате YAML или JSON. Это можно делать с помощью Swagger Editor (онлайн-редактор) — онлайн-редактора, который позволяет создавать и редактировать спецификацию OpenAPI в удобном интерфейсе.

Разница между OpenAPI и Swagger​

  • OpenAPI — это спецификация.
  • Swagger — это инструментарий, использующий спецификацию OpenAPI. Например, OpenAPIGenerator и SwaggerUI.

Подборка материалов по изучению OpenAPI и Swagger​

Официальная документация​

Открытый курс по документированию API​

Статьи​

  1. OpenAPI/Swagger для начинающих
  2. Как построить REST-like API в крупном проекте
  3. Как ускорить тестирование приложения с помощью OpenAPI-спецификаций

Видео​

  1. Что такое Swagger и OpenAPI за 3 минуты
  2. Плейлист — OpenAPI и Swagger за 1 час

Практические примеры​

  1. Знакомимся со Swagger на примере собственного веб-приложения с REST API
  2. Пишем спецификацию OpenAPI для интернет-магазина в Swagger
  3. Аутентификация в спецификации OpenAPI: расширенный пример интернет-магазина с JWT
  4. Небольшой пример от Госуслуг

Примеры готовых спецификаций OpenAPI​

  1. Спецификация GitHub
  2. Тестовый SwaggerUI
  3. Blockchain.com Exchange REST API — сваггер популярной биржи криптовалют
  4. Kraken REST API — пример подробной документации API и спецификации в формате OpenAPI + примеры кода на Python

Инструменты​

  1. stoplight.io — позволяет упростить написание и ведение спецификаций