swaggo/swag

Что это?

Ключевые возможности

• 01Генерирует спецификации Swagger 2.0 в форматах JSON и YAML, а также Go-пакет docs.
• 02Описывает эндпоинты с помощью аннотаций в комментариях над функциями-обработчиками Go.
• 03Поддерживает параметры запросов, ответы, заголовки, определения безопасности и теги.
• 04Читает теги полей структур с примерами, правилами валидации и перечислениями.
• 05Предоставляет middleware для Gin, Echo, Fiber, net/http, chi и других фреймворков.
• 06Включает команду swag fmt для форматирования комментариев с аннотациями.

Сценарии использования

• Генерация документации API для REST-сервиса на Go без ручного ведения отдельного файла OpenAPI.
• Публикация интерактивной страницы Swagger UI для бэкенда на Gin или Echo.
• Поддержание актуальности документации API в соответствии с кодом обработчиков во время сборок CI.

Быстрый старт

1. 1

   Установите CLI swag с помощью Go

   go install github.com/swaggo/swag/cmd/swag@latest
2. 2

   Добавьте аннотации API в комментарии исходного кода на Go

3. 3

   Запустите swag init в корне проекта, где находится main.go, чтобы сгенерировать документацию

   swag init

Что важно знать

• !Генерирует документацию только в формате Swagger 2.0, без поддержки OpenAPI 3.x.
• !Аннотации нужно писать в комментариях Go, а после изменений документацию необходимо генерировать заново.

Темы

Частые вопросы

Что такое swag?

Инструмент для Go, который генерирует документацию API в формате Swagger 2.0 по аннотациям в комментариях к исходному коду. Swag разбирает комментарии специального формата в коде на Go, например над обработчиками и определениями структур, и генерирует документацию Swagger 2.0 в виде файлов swagger.json, swagger.yaml и docs.go. Разработчики добавляют над обработчиками аннотации вроде @Summary, @Param, @Success и @Router, а затем запускают swag init, чтобы обновить спецификацию.

swag можно использовать бесплатно? Какая у него лицензия?

swag распространяется с открытым исходным кодом под лицензией MIT. Перед использованием в коммерческих продуктах проверьте условия лицензии.

swag всё ещё поддерживается?

Обновлялся за последние 6 месяцев. Последний коммит в swag — 30 сент. 2026 г..

Для чего можно использовать swag?

Генерация документации API для REST-сервиса на Go без ручного ведения отдельного файла OpenAPI. Публикация интерактивной страницы Swagger UI для бэкенда на Gin или Echo. Поддержание актуальности документации API в соответствии с кодом обработчиков во время сборок CI.

Как установить swag?

Установите CLI swag с помощью Go: go install github.com/swaggo/swag/cmd/swag@latest Добавьте аннотации API в комментарии исходного кода на Go Запустите swag init в корне проекта, где находится main.go, чтобы сгенерировать документацию: swag init

Где скачать swag?

Исходный код и инструкции по установке — на GitHub: https://github.com/swaggo/swag