ogen - Efficient Go Code Generation from OpenAPI v3 Without Reflection

Introduction to the Ogen Project

Ogen is an innovative project that aims to simplify the process of generating Go code from OpenAPI v3 specifications. It stands out as a robust OpenAPI code generator, tailored specifically for the Go programming language, offering a wealth of features to streamline API development.

Installation and Usage

To get started with Ogen, users can easily install it by running the following command:

go get -d github.com/ogen-go/ogen

Once installed, Ogen can be used to generate code as shown in the example below:

//go:generate go run github.com/ogen-go/ogen/cmd/ogen --target target/dir -package api --clean schema.json

Alternatively, users can leverage Docker for code generation:

docker run --rm \
  --volume ".:/workspace" \
  ghcr.io/ogen-go/ogen:latest --target workspace/petstore --clean workspace/petstore.yml

Notable Features

Ogen provides a variety of features that differentiate it from other code generators:

Reflection-Free: It avoids the use of Go's interface{} and reflection, opting instead for code-generated, optimized JSON encoding using go-faster/jx, resulting in faster performance.
Static Radix Router: A code-generated router enhances efficiency and simplicity.
No Boilerplate Code: Structures and various elements like arguments, headers, and URL queries are generated according to the OpenAPI specification.
Typed Client and Server: Both client and server code are strongly typed, which inherently reduces errors and improves code readability.
Support for Optional and Nullable Fields: Ogen generates specific wrappers for optional and nullable fields, making the handling of such fields more intuitive.
Sum Types for OneOf: Automatically generated sum types simplify dealing with schema types defined by oneOf.
OpenTelemetry Integration: Tracing and metrics functionality is integrated to assist in performance monitoring.

Example Code

Here's a snapshot of what a generated structure might look like:

// Pet describes #/components/schemas/Pet.
type Pet struct {
	Birthday     time.Time     `json:"birthday"`
	Friends      []Pet         `json:"friends"`
	ID           int64         `json:"id"`
	...
}

And an example of a generated server interface might be:

// Server handles operations described by OpenAPI v3 specification.
type Server interface {
	PetGetByName(ctx context.Context, params PetGetByNameParams) (Pet, error)
	// ...
}

Dealing with Generics and Recursive Types

Ogen incorporates generics to handle optional and nullable values without resorting to pointers. In scenarios where recursive types are encountered, it intelligently switches to using pointers.

Extension Properties and Advanced Customizations

Ogen supports several OpenAPI extensions, allowing for greater customization:

Server and Type Naming: Custom names can be assigned using extensions like x-ogen-server-name and x-ogen-name.
JSON Streaming: For more efficient data processing, streaming JSON support can be enabled.
Operation Grouping: Handlers for specific groups of operations can be generated, aiding organization in large APIs.

Links and Resources

For more information, the following resources are available:

Ogen provides developers with a powerful tool to generate efficient, reliable code swiftly, while accommodating complex API schemas with ease. Its robust feature set and seamless integration with Go make it an invaluable resource for API development.