Skip to main content

ogen v1.25.0

ogen v1.25.0 adds Swagger UI out of the box, works with Go 1.27.2, and fixes a dozen generator bugs. Nine people made their first contribution to this release. Thank you!

Upgrade​

go get -tool github.com/ogen-go/ogen/cmd/ogen@v1.25.0
go generate ./...

Both new features are opt-in. With the default config, the generated code changes only where the bug fixes below apply.

Swagger UI and the embedded spec​

Two new features serve the OpenAPI document from the generated server (#1775):

  • server/spec embeds the document and generates SpecJSON(), SpecYAML(), SpecHandler() and the WithDocs server option.
  • server/swagger_ui also serves Swagger UI. It implies server/spec.
.ogen.yml
generator:
  features:
    enable:
      - server/swagger_ui
srv, err := api.NewServer(handler, api.WithDocs("/docs"))
// http://localhost:8080/docs/             Swagger UI
// http://localhost:8080/docs/openapi.json the spec

Swagger UI assets ship in the swaggerui package, which uses only the standard library. To load them from a CDN instead, use WithDocsAssetsURL. The generator.spec_source option (auto, raw, expanded) picks which document gets embedded: the original file, or a self-contained one with external $refs resolved.

Struct aliases that keep methods​

When several content types or response codes share one schema, ogen generates a named type for each of them:

type CreatePetOK Pet

Go drops the methods of Pet from such a type. The new schema/embed_struct_aliases feature generates an embedding instead, so the methods carry over and a single interface covers all the variants (#1789):

type CreatePetOK struct {
	Pet
}

This changes the generated API (CreatePetOK(pet) becomes CreatePetOK{pet}), so the feature is off by default.

Go 1.27.2​

ogen now builds and runs on Go 1.27.2 with JSON v2 enabled. GOEXPERIMENT=nojsonv2 is no longer needed (#1774).

Fixes​

Generated code that failed to compile:

  • Responses that share an inline header schema (#1769).
  • Constant uri and other string formats (#1752).
  • Object-level x-ogen-validate (#1772).
  • uniqueItems arrays of MAC addresses (#1788).
  • Webhooks with security. NewWebhookServer now takes a SecurityHandler, and NewWebhookClient takes a SecuritySource, but only when some webhook requires security (#1771).
  • A security requirement that combines schemes with AND, one of them unsupported and listed in ignore_not_implemented (#1760).

Wrong behavior:

  • A default set next to a $ref applied to every use of that schema, not just that one (#1758).
  • The client sent an empty value for unset optional parameters with structured content. Now it omits them (#1741).
  • Decoding null into a nullable array kept the old value (#1789).
  • allOf merging dropped x-ogen-time-format (#1778).

Smaller fixes:

  • min/max conflict errors now name the real keywords, like minLength (#1733).
  • A path like /caf%e9/100% crashed ogen with a panic. Now ogen reports an invalid escape (#1732).

The full list of changes is in the release notes.