Перейти на PRO

Какие инструменты для генерации OpenAPI (Swagger) документации в Go вы использовали?

Тип вопроса: Golang Вероятность: 10% Категория: Golang Разработчик

Ответ

Для автоматической генерации OpenAPI-документации в Go я работал с двумя основными инструментами: Swaggo (swag) и go-swagger.

1. Swaggo (swag)

Это самый популярный инструмент, работающий по принципу code-first. Документация генерируется на основе комментариев-аннотаций прямо в коде.

  • Процесс работы:

    1. Добавляются аннотации к хендлерам API.
    2. Запускается команда swag init.
    3. Инструмент генерирует docs директорию с файлами swagger.json, swagger.yaml и docs.go.

  • Пример аннотации для gin:

    // @Summary      Получить пользователя по ID
// @Description  Возвращает данные одного пользователя
// @Tags         users
// @Accept       json
// @Produce      json
// @Param        id   path      int  true  "ID пользователя"
// @Success      200  {object}  models.User
// @Failure      404  {object}  httputil.HTTPError
// @Router       /users/{id} [get]
func GetUser(c *gin.Context) { ... }

  • Плюсы: Простота, быстрая интеграция, документация всегда рядом с кодом.

  • Минусы: Ограниченная поддержка сложных типов (например, дженериков), ошибки в аннотациях могут приводить к некорректной генерации.

2. go-swagger

Более мощный и гибкий инструмент, который хорошо подходит для подхода spec-first, когда сначала пишется спецификация, а затем на её основе генерируется код.

  • Основные возможности:

    • Генерация сервера и клиента на основе swagger.yml файла.
    • Валидация запросов и моделей на основе спецификации.
    • Генерация спецификации из кода (менее популярный сценарий).

  • Процесс работы (spec-first):

    1. Вручную или в редакторе создается swagger.yml.
    2. Командой swagger generate server ... создается каркас приложения.
    3. Разработчик реализует бизнес-логику в сгенерированных хендлерах.

Сравнение и выбор

Критерий Swaggo go-swagger
Подход Code-first (код первичен) Spec-first (спецификация первична)
Сложность Простой Средний / Сложный
Гибкость Низкая Высокая
Лучший сценарий Быстрая разработка, небольшие и средние проекты Крупные проекты, строгие контракты API, микросервисы

В большинстве проектов я предпочитаю Swaggo за его простоту. Для сложных систем, где важен строгий контракт API, go-swagger является более надежным решением.

Ответ 18+ 🔞

А, ну вот, подъехали к моей любимой теме — генерации документации на Go. Сидишь такой, пишешь API, а потом тебе говорят: «А где, блядь, документация?». И тут начинается цирк, ёпта.

Так вот, есть два главных клоуна на этой арене: Swaggo и go-swagger. И они, сука, как два разных подхода к жизни.

1. Swaggo (он же swag)

Это такой парень, который сначала делает, а потом думает. Code-first, блядь. Ты пишешь код, накидываешь в него комментариев, как будто это объедки со стола, а потом он из этого делает конфетку.

  • Как это работает, а?

    1. Ты пишешь хендлер, а над ним начинаешь хуярить аннотации, как будто это граффити на заборе.
    2. Потом кричишь в терминал swag init.
    3. И он, хитрая жопа, генерирует тебе папочку docs с файликами swagger.json, swagger.yaml и docs.go. Всё, готово, можно показывать.

  • Вот смотри, как это выглядит для gin (примерно так я и пишу):

    // @Summary      Получить пользователя по ID
// @Description  Возвращает данные одного пользователя
// @Tags         users
// @Accept       json
// @Produce      json
// @Param        id   path      int  true  "ID пользователя"
// @Success      200  {object}  models.User
// @Failure      404  {object}  httputil.HTTPError
// @Router       /users/{id} [get]
func GetUser(c *gin.Context) { ... }

    Выглядит как заклинание, но работает, ёбана!

  • Плюсы: Проще некуда, вьебался в проект за пять минут, и документация всегда приклеена к коду, как жвачка к ботинку.

  • Минусы: Если накосячишь в этих аннотациях — получишь такую кашу в swagger.json, что сам от себя охуеешь. И с какими-нибудь хитрожопыми типами данных может затупить.

2. go-swagger

А вот это уже серьёзный дядя. Он любит порядок. Сначала план, чертёж, спецификация, а потом уже код. Spec-first, блядь. Ты сначала пишешь swagger.yml, а потом он тебе из него сервер как из конструктора собирает.

  • На что способен этот монстр:

    • Может сгенерить весь каркас сервера или клиента по готовой спецификации. Красота!
    • Валидирует входящие запросы по этой же спецификации. Никакого самодеятельного говна.
    • Может и наоборот — из кода спецификацию вытянуть, но это как-то не очень популярно.

  • Процесс (когда ты решил жить по правилам):

    1. Сидишь, ковыряешься в swagger.yml, вылизываешь каждую строчку.
    2. Командуешь: swagger generate server ....
    3. Получаешь готовый скелет приложения, в который остаётся только мясо бизнес-логики запихнуть.

Так что же выбрать? Сравнительная таблица на коленке

Критерий Swaggo go-swagger
Философия Сначала код, потом болтовня (Code-first) Сначала план, потом стройка (Spec-first)
Сложность входа Как влить пиво — просто Как собрать мебель из IKEA — инструкция есть, но хуй знает
Степень свободы Ограниченная, но для большинства хватает Высокая, можно выёбываться как хочешь
Идеальный случай Быстрая разработка, пет-проекты, микросервисы среднего калибра Крупные, сложные системы, где контракт API — это святое

Итог: В 80% случаев я хватаю Swaggo, потому что он быстрый и не грузит мозги. Но если вижу, что проект вырастет в нечто монструозное, где каждый чих должен быть задокументирован, или если работаю в команде, где дизайн API обсуждают отдельно — тогда без вариантов, go-swagger. Иначе потом будешь сидеть и переписывать все эти аннотации, материться, как сапожник.

© ХакСобесов, 2026
support@hacksobesov.com