Библиотека Go-разработчика | Golang: “🔄 oapi-codegen v2.7.0 Вышел релиз oapi-codegen v2.7.0. Это Go-инструм…”

🔄 oapi-codegen v2.7.0

Вышел релиз oapi-codegen v2.7.0. Это Go-инструмент, который генерирует серверный и клиентский код из OpenAPI-спецификаций. Версия исправляет проблемы с allOf/anyOf/oneOf, внешними $ref, перечислениями и обходом схем.

Три изменения, которые затронут существующий код

1. Strict-server с внешними $ref на ответы

Если strict-server использует внешний $ref на components/responses/... из другой спецификации, эта спецификация теперь тоже должна генерироваться с strict-server: true.

Добавьте в конфиг источника:

generate:
  models: true
  strict-server: true

2. Переименование анонимных схем

Анонимные схемы внутри oneOf, anyOf и additionalProperties теперь генерируются по единому шаблону:

GetPets_200_Data_Item            →  GetPets200JSONResponseBody_Data_Item
GetPets200JSONResponse_Data_Item →  GetPets200JSONResponseBody_Data_Item

3. Инлайн middleware-типы в strict-server

StrictHandlerFunc и StrictMiddlewareFunc больше не являются алиасами к типам из пакета runtime/strictmiddleware/<framework>.

Теперь они определяются прямо в сгенерированном коде:

// было
import strictecho "github.com/oapi-codegen/runtime/strictmiddleware/echo"
type StrictHandlerFunc = strictecho.StrictEchoHandlerFunc

// стало
type StrictHandlerFunc func(ctx echo.Context, request any) (any, error)

Если вы ссылались на типы вида strictecho.StrictEchoHandlerFunc напрямую, замените их на StrictHandlerFunc из сгенерированного пакета.

Что нового

Разрешение коллизий имён. Новая опция output-options.resolve-type-name-collisions: true позволяет генерировать код, когда два разных определения претендуют на одинаковое Go-имя.

Коллизия разрешается детерминированно через суффикс:

type Status string          // из components.schemas.Status
type StatusParameter = string  // из components.parameters.Status

Опция отключена по умолчанию.

Полная матрица параметров. Теперь поддерживаются все комбинации style × explode × type для параметров пути, запроса, заголовков и куки. Если раньше падала ошибка unsupported style или поведение отличалось в разных бэкендах, регенерация должна это исправить. Требуется github.com/oapi-codegen/runtime версии v1.4.0 или выше.

Опциональные заголовки ответов. В strict-server необязательные заголовки теперь генерируются как указатели. Если поле nil, заголовок не отправляется:

// было
type GetFoo200ResponseHeaders struct {
    XOptional string  // всегда в ответе, даже пустым
}

// стало
type GetFoo200ResponseHeaders struct {
    XOptional *string  // nil — заголовок не отправляется
}

Старое поведение возвращается через compatibility.headers-implicitly-required: true.

Echo v5. Добавлена поддержка Echo v5 через флаг generate.echo5-server: true. Echo v4 не затронут.

Middleware на уровне операций в Echo. В RegisterHandlersWithOptions появился OperationMiddlewares:

api.RegisterHandlersWithOptions(e, server, api.RegisterHandlersOptions{
    OperationMiddlewares: map[string][]echo.MiddlewareFunc{
        "createPet": {authMiddleware, auditMiddleware},
    },
})

Middleware на уровне хендлеров в Fiber. В FiberServerOptions появился слайс HandlerMiddlewares []HandlerMiddlewareFunc.

Обработчики ошибок в strict-server для Gin. Теперь Gin поддерживает RequestErrorHandlerFunc и ResponseErrorHandlerFunc в StrictServerOptions, как это уже было в Echo.

Требования к окружению

Для сборки и запуска oapi-codegen теперь нужен Go 1.24.4+. Сгенерированный код по-прежнему может работать на более старых версиях. Из-за транзитивных зависимостей может потребоваться зафиксировать версии:

github.com/speakeasy-api/jsonpath v0.6.3
github.com/dprotaso/go-yit v0.0.0-20220510233725-9ba8df137936

➡️ Репозиторий

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

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

#GoLive