Swagger/OpenAPI генерация для Go (Golang): полное руководство

Swagger/OpenAPI генерация для Go (Golang)

При разработке веб-сервисов на Go (Golang) одной из ключевых задач является создание качественной и актуальной документации API. Swagger (теперь известный как OpenAPI) стал отраслевым стандартом для описания RESTful интерфейсов. В этой статье мы рассмотрим основные инструменты для генерации OpenAPI спецификаций в экосистеме Go, их установку, настройку и практическое применение.

Почему OpenAPI важен для Go-разработчика?

OpenAPI позволяет создавать машиночитаемое описание вашего API, которое можно использовать для:

• Автоматической генерации клиентских библиотек на разных языках
• Создания интерактивной документации (Swagger UI)
• Валидации входящих и исходящих запросов
• Тестирования API с помощью инструментов вроде Postman или Insomnia

Основные библиотеки для генерации OpenAPI в Go

1. swaggo/swag — самый популярный выбор

Библиотека swaggo/swag является де-факто стандартом для генерации Swagger документации в Go. Она работает на основе аннотаций в комментариях к коду.

Установка:

go get -u github.com/swaggo/swag/cmd/swag
go get -u github.com/swaggo/gin-swagger  // для Gin фреймворка
go get -u github.com/swaggo/files

Пример использования с Gin:

package main

import (
    "github.com/gin-gonic/gin"
    "github.com/swaggo/gin-swagger"
    "github.com/swaggo/files"
    _ "your-module/docs" // сгенерированный пакет
)

// @title           My API
// @version         1.0
// @description     Пример API на Go с Swagger
// @host            localhost:8080
// @BasePath        /api/v1

func main() {
    r := gin.Default()
    
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    
    r.GET("/api/v1/users", GetUsers)
    r.Run(":8080")
}

// GetUsers возвращает список пользователей
// @Summary      Получить список пользователей
// @Description  Возвращает всех пользователей системы
// @Tags         users
// @Accept       json
// @Produce      json
// @Success      200  {array}   User
// @Router       /users [get]
func GetUsers(c *gin.Context) {
    users := []User{{ID: 1, Name: "Иван"}}
    c.JSON(200, users)
}

type User struct {
    ID   int    `json:"id" example:"1"`
    Name string `json:"name" example:"Иван"`
}

После написания кода выполните команду:

swag init

Это создаст папку docs с файлами swagger.json и swagger.yaml.

2. go-swagger — мощный, но более сложный инструмент

go-swagger предоставляет не только генерацию документации из кода, но и обратный процесс — генерацию кода из спецификации.

Установка:

go get -u github.com/go-swagger/go-swagger/cmd/swagger

Пример генерации сервера из спецификации:

swagger generate server -f ./swagger.yaml -A my-api

Генерация документации из кода:

// swagger:route GET /users users listUsers
// Возвращает список пользователей.
// responses:
//   200: usersResponse

func ListUsersHandler(w http.ResponseWriter, r *http.Request) {
    // реализация
}

3. oapi-codegen — современный подход с кодогенерацией

Библиотека oapi-codegen позволяет генерировать типы, серверные заглушки и клиенты на основе OpenAPI спецификации.

Установка:

go get -u github.com/deepmap/oapi-codegen/cmd/oapi-codegen

Пример использования:

Сначала создайте файл api.yaml:

openapi: "3.0.0"
info:
  title: My API
  version: "1.0"
paths:
  /users:
    get:
      operationId: listUsers
      responses:
        '200':
          description: Список пользователей
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

Затем выполните генерацию:

oapi-codegen -package main api.yaml > api.gen.go

В результате вы получите готовый Go-код с типами и интерфейсами.

Сравнение