🔄 Документирование API или что такое Swagger/OpenAPI

Документация позволяет разработчикам удобнее работать с API. Она содержит информацию о том, какие эндпоинты существуют в сервисе и как с ними взаимодействовать.

🔄 Лучшей практикой документации является спецификация OpenAPI - универсальный способ описания API в YAML или JSON-формате, который может использоваться с любым языком программирования. Раньше спецификация называлась Swagger и только при появлении версии 3.0 стала называться OpenAPI и стала open-source проектом.

🔥 Когда нужно быстро написать документацию, можно использовать библиотеку генерации спецификации OpenAPI, поддерживаемую вашим фреймворком, например, drf-spectacular для Django Rest Framework. Такие библиотеки позволяют сгенерировать файл с описанием API автоматически на основе исходного кода, однако описание и параметры для каждого эндпоинта разработчику нужно будет прописывать вручную.

Если у вас нет доступа к коду, можно написать spec-файл вручную в Swagger Editor, где есть онлайн-проверка корректности синтаксиса и отображение готовой документации через Swagger UI.

Готовый spec-файл можно загрузить в Swagger UI, который отобразит документацию в удобном виде.

☕️ Расскажите в комментариях, документируете ли вы API?