Библиотека Go-разработчика | Golang: “🔥Автодокументация API в Go: Gin + Swaggo Вы пишете API на Gin, фронте…”

🔥Автодокументация 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 перезапускает сервер при изменениях.

📍 Навигация: Вакансии • Задачи • Собесы • Канал в Max

🐸 Библиотека Go-разработчика

#GoToProduction