🔥Автодокументация API в Go: Gin + Swaggo — 31 мая 2026 г. в 14:07:43.701
🔥Автодокументация API в Go: Gin + Swaggo Вы пишете API на Gin, фронтенд-команда просит документацию, а вы обновляете её вручную в Notion или Confluence. Через неделю доки расходятся с кодом, и начинается хаос. Swaggo решает эту проблему. Вы пишете комментарии прямо в коде, а он генерирует интерактивную документацию по спецификации OpenAPI. Как это работает Swaggo парсит специальные комментарии над хендлерами Gin и на их основе собирает swagger.json. Результат можно открыть в браузере через Swagger UI. Устанавливаем CLI: go install github.com/swaggo/swag/cmd/swag@latest Добавляем зависимости в проект: go get github.com/swaggo/gin-swagger go get github.com/swaggo/files Пишем хендлер с аннотациями: // @Summary Получить профиль пользователя // @Description Парсит токен из заголовка и возвращает данные пользователя // @Produce json // @Success 200 {object} profileResponse // @Router /api/v2/account/profile [get] func FetchProfileHandler(c *gin.Context) { c.JSON(http.StatusOK, gin.H{"status": "ok", "data": "user_data"}) } Подключаем Swagger UI в роутере: import ( swaggerFiles "github.com/swaggo/files" ginSwagger "github.com/swaggo/gin-swagger" _ "your-project/docs" ) r := gin.Default() r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) Генерируем документацию: swag init После этого по адресу /swagger/index.html будет доступна интерактивная страница со всеми эндпоинтами. Фронтенд-команда видит актуальные контракты, может отправлять тестовые запросы прямо из браузера. Что умеют аннотации Swaggo поддерживает описание query-параметров, тела запроса, заголовков, кодов ответа и моделей данных. Всё через комментарии над функцией. Пример с параметрами: // @Summary Список пользователей // @Param page query int false "Номер страницы" default(1) // @Param limit query int false "Количество на странице" default(20) // @Success 200 {array} User // @Router /api/v2/users [get] Модели берутся из Go-структур. Если User определён в коде, Swaggo автоматически подтянет его поля в документацию. Hot reload с Air При активной разработке удобно, чтобы сервер перезапускался при каждом сохранении файла. Для этого используют Air. Установка: go install github.com/air-verse/air@latest Запуск в корне проекта: air Air следит за изменениями в .go файлах, пересобирает и перезапускает сервер. Работает быстро, конфигурируется через .air.toml. В связке с Swaggo можно добавить swag init в команду сборки, и документация будет обновляться вместе с кодом. Gin отвечает за роутинг и производительность. Swaggo превращает комментарии в OpenAPI-документацию. Air перезапускает сервер при изменениях.