Канал для системных аналитиков и не только: подборки полезных материалов на все случаи жизни.
Реклама и сотрудничество @radale
https://gosuslugi.ru/snet/67b0613c6411ff785396754a
Post #210
10.7K
😌 Документирование 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
➿➿➿➿➿➿➿➿
🧑🎓 Больше полезного в базе знаний по системному анализу
Как известно, 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
➿➿➿➿➿➿➿➿
🧑🎓 Больше полезного в базе знаний по системному анализу
- 👍 33
- 🔥 26
- ❤ 9







