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

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

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

Разрабатывать документацию по 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

🌐 Официальная документация:
OpenAPI, Swagger

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

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

✏️ Примеры готовых спецификаций OpenAPI
1. Спецификация GitHub
2. Тестовый SwaggerUI

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

#проектирование #api

➿➿➿➿➿➿➿➿

🧑‍🎓 Больше полезного в базе знаний по системному анализу