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

Для автоматической генерации 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 за его простоту. Для сложных систем, где важен строгий контракт API, go-swagger является более надежным решением.