Swagger/OpenAPI генерация для Go (Golang): go-swagger и oapi-codegen

Swagger/OpenAPI генерация для Go (Golang): go-swagger и oapi-codegen

Разработка современных веб-сервисов на Go требует строгой спецификации API. OpenAPI (ранее известный как Swagger) — это стандарт описания RESTful интерфейсов, который позволяет автоматизировать создание клиентов, серверов и документации. В экосистеме Go существует два ключевых инструмента для генерации кода из OpenAPI-спецификаций: go-swagger и oapi-codegen. В этой статье мы подробно разберём оба подхода, их установку и практическое применение.

Что такое OpenAPI и зачем генерировать код?

OpenAPI Specification (OAS) — это формат файла (обычно YAML или JSON), который описывает эндпоинты, параметры, типы данных и схемы ответов вашего API. Вместо того чтобы вручную писать обработчики, модели и валидацию, вы можете:

• Сгенерировать серверный код с маршрутами и middleware.
• Сгенерировать клиентский SDK для других сервисов.
• Автоматически обновлять документацию (Swagger UI).
• Избежать рассинхронизации между спецификацией и реализацией.

Инструмент №1: go-swagger

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

Установка go-swagger

# Установка через go install (Go 1.17+)
go install github.com/go-swagger/go-swagger/cmd/swagger@latest

# Проверка установки
swagger version

Генерация сервера из спецификации

Предположим, у нас есть файл api.yaml:

openapi: "3.0.0"
info:
  title: Pet Store
  version: "1.0.0"
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      responses:
        '200':
          description: A list of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

Выполните генерацию сервера:

swagger generate server -f api.yaml -A petstore -t ./gen

После выполнения в папке ./gen появятся:

• restapi/ — обработчики и маршруты.
• models/ — структуры данных (Pet, Error и т.д.).
• cmd/ — точка входа в приложение.

Пример реализации обработчика

package restapi

import (
    "net/http"
    "petstore/gen/models"
    "petstore/gen/restapi/operations"
)

func configureAPI(api *operations.PetstoreAPI) http.Handler {
    api.ListPetsHandler = operations.ListPetsHandlerFunc(
        func(params operations.ListPetsParams) middleware.Responder {
            pets := []*models.Pet{
                {ID: 1, Name: "Buddy"},
                {ID: 2, Name: "Milo"},
            }
            return operations.NewListPetsOK().WithPayload(pets)
        },
    )
    return api.Serve(nil)
}

Инструмент №2: oapi-codegen

oapi-codegen — это современный, лёгкий и очень быстрый генератор от команды DeepMap. Он поддерживает OpenAPI 3.0 и фокусируется на минимализме. Рекомендуется для новых проектов.

Установка oapi-codegen

go install github.com/deepmap/oapi-codegen/v2/cmd/oapi-codegen@latest

Генерация типов и сервера

Используем ту же спецификацию api.yaml. Выполните:

oapi-codegen -generate types,server -package petstore api.yaml > petstore.gen.go

Флаг -generate позволяет выбрать, что генерировать:

• types — Go-структуры для схем.
• server — интерфейсы сервера.
• client — HTTP-клиент.
• spec — встраивание спецификации.

Пример реализации с oapi-codegen

package main

import (
    "net/http"
    "petstore"
)

type Server struct{}

func (s *Server) ListPets(w http.ResponseWriter, r *http.Request, params petstore.ListPetsParams) {
    pets := []petstore.Pet{
        {Id: 1, Name: