Skip to main content

Configuration

ogen can be configured via a YAML file passed with the --config flag:

go tool ogen --config .ogen.yml --target petstore --clean petstore.yml

Adding the schema annotation at the top of the file enables autocompletion and validation in editors that support the YAML language server:

.ogen.yml
# yaml-language-server: $schema=https://raw.githubusercontent.com/ogen-go/ogen/main/schemas/ogen.jsonschema.json

The configuration has two main sections: parser controls how the OpenAPI document is read, and generator controls what code is produced.

Features​

ogen provides an opt-in/opt-out mechanism for features such as OpenTelemetry integration, client and server generation, and request validation.

.ogen.yml
generator:
  features:
    enable:
      # Generate client code for API paths.
      - "paths/client"
      # Generate server code for API paths.
      - "paths/server"
      # Enable OpenTelemetry integration.
      - "ogen/otel"
    disable:
      # Disable server response validation.
      - "server/response/validation"

Features are resolved in three steps: start from the default set (unless disable_all is true), apply disable, then apply enable. Entries in enable always take priority.

The default feature set is:

- paths/client
- paths/server
- webhooks/client
- webhooks/server
- ogen/otel
- ogen/unimplemented

You can find the complete feature list in the ogen repository.

Generate only a client​

To generate a client without any server code, disable everything and enable just the client features:

.ogen.yml
generator:
  features:
    enable:
      - client/editors
      - client/request/options
      - ogen/otel
      - ogen/unimplemented
      - paths/client
      - webhooks/client
    disable_all: true

Disable OpenTelemetry​

OpenTelemetry is enabled by default. Disable it to drop the dependency and the instrumentation code:

.ogen.yml
generator:
  features:
    disable:
      - "ogen/otel"

Skipping unsupported operations​

Some real-world specifications contain constructs that ogen cannot yet generate. By default, generation fails on the first such error. Use ignore_not_implemented to skip those operations instead:

.ogen.yml
generator:
  # Skip all not-implemented generation errors.
  ignore_not_implemented: ["all"]

You can also skip only specific cases, which keeps the rest of the specification strict:

.ogen.yml
generator:
  ignore_not_implemented:
    - "nested objects in form parameters"

Filters​

Generate code for a subset of the specification by path or HTTP method:

.ogen.yml
generator:
  filters:
    # Only paths matching this regular expression are generated.
    path_regex: "^/api/v1/.*"
    # Only these methods are generated.
    methods:
      - GET
      - POST

Type inference​

When a schema omits an explicit type, ogen can infer it from the schema's properties. This is required for many large real-world specs such as the GitHub or Kubernetes APIs:

.ogen.yml
parser:
  infer_types: true

Full example​

A configuration combining the most common options, similar to what is used to generate the GitHub API client:

.ogen.yml
# yaml-language-server: $schema=https://raw.githubusercontent.com/ogen-go/ogen/main/schemas/ogen.jsonschema.json

parser:
  # Detect schema type from its properties.
  infer_types: true

generator:
  features:
    enable:
      - "paths/client"
      - "paths/server"
      - "ogen/otel"
    disable_all: true
  # Skip operations that are not yet supported.
  ignore_not_implemented: ["all"]

See the full reference config, which documents every available option with example values, and the default config, which shows all defaults.