Configuration Reference

# The Go package name for generated code.
# Can also be set with -package flag.
package: myapi

# Output file path.
# Can also be set with -output flag.
# Default: <spec-basename>.gen.go
output: types.gen.go

# Generation controls which parts of the code are generated.
generation:
  # Server framework to generate code for.
  # Supported: "std-http", "chi", "echo", "echo/v4", "gin", "gorilla", "fiber", "iris"
  # Default: "" (no server code generated)
  server: std-http

  # Generate an HTTP client that returns *http.Response.
  # Default: false
  client: true

  # Generate a SimpleClient wrapper with typed responses.
  # Requires client: true.
  # Default: false
  simple-client: true

  # Generate webhook initiator code (sends webhook requests to target URLs).
  # Generates a framework-agnostic client that takes the full target URL per-call.
  # Default: false
  webhook-initiator: true

  # Generate webhook receiver code (receives webhook requests).
  # Generates framework-specific handler functions. Requires server to be set.
  # Default: false
  webhook-receiver: true

  # Generate callback initiator code (sends callback requests to target URLs).
  # Default: false
  callback-initiator: true

  # Generate callback receiver code (receives callback requests).
  # Generates framework-specific handler functions. Requires server to be set.
  # Default: false
  callback-receiver: true

  # Use model types from an external package instead of generating them locally.
  # When set, models are imported rather than generated.
  # Default: not set (models are generated locally)
  models-package:
    path: github.com/org/project/models
    alias: models  # optional, defaults to last segment of path

  # Use a shared runtime package instead of embedding helpers in each generated file.
  # When set, custom types (Date, Email, UUID, File, Nullable), parameter
  # serialization functions, and helper functions (MarshalForm) are NOT embedded
  # in the output. Instead, the generated code imports them from three sub-packages:
  #   <path>/types   — custom types (Date, Email, UUID, File, Nullable)
  #   <path>/params  — parameter style/bind functions (StyleSimpleParam, BindFormParam, etc.)
  #   <path>/helpers — utility functions (MarshalForm)
  #
  # Generate the runtime package once with:
  #   oapi-codegen --generate-runtime <base-import-path>
  #
  # Default: not set (all helpers are embedded in each generated file)
  runtime-package:
    path: github.com/org/project/runtime

  # Disable detection of the OpenAPI 3.1 enum-via-oneOf idiom. When a schema
  # declares a scalar `type` with `oneOf` branches that each carry `const` and
  # `title`, oapi-codegen emits a Go enum with named constants (from `title`)
  # and per-value doc comments (from `description`) instead of a oneOf union.
  # Set to true to keep the legacy union output for those schemas.
  # Default: false
  skip-enum-via-oneof: false

# Output options: control which operations and schemas are included.
output-options:
  # Only include operations tagged with one of these tags. Ignored when empty.
  include-tags:
    - public
    - beta
  # Exclude operations tagged with one of these tags. Ignored when empty.
  exclude-tags:
    - internal
  # Only include operations with one of these operation IDs. Ignored when empty.
  include-operation-ids:
    - listPets
    - createPet
  # Exclude operations with one of these operation IDs. Ignored when empty.
  exclude-operation-ids:
    - deprecatedEndpoint
  # Exclude schemas with the given names from generation. Ignored when empty.
  exclude-schemas:
    - InternalConfig

# Type mappings: OpenAPI type/format to Go type.
# User values are merged on top of defaults — you only need to specify overrides.
type-mapping:
  integer:
    default:
      type: int          # default
    formats:
      int32:
        type: int32      # default
      int64:
        type: int64      # default
  number:
    default:
      type: float32      # default
    formats:
      double:
        type: float64    # default
  boolean:
    default:
      type: bool         # default
  string:
    default:
      type: string       # default
    formats:
      byte:
        type: "[]byte"                         # default
      date:
        type: Date                             # default, custom template type
      date-time:
        type: time.Time                        # default
        import: time
      uuid:
        type: UUID                             # default, custom template type
      email:
        type: Email                            # default, custom template type
      binary:
        type: File                             # default, custom template type
      json:
        type: json.RawMessage                  # default
        import: encoding/json
      # Add your own format mappings:
      money:
        type: decimal.Decimal
        import: github.com/shopspring/decimal

# Name mangling: controls how OpenAPI names become Go identifiers.
# User values are merged on top of defaults.
name-mangling:
  # Prefix prepended when a name starts with a digit.
  # Default: "N" (e.g., "123foo" becomes "N123foo")
  numeric-prefix: "N"

  # Prefix prepended when a name conflicts with a Go keyword.
  # Default: "" (uses keyword-suffix instead)
  keyword-prefix: ""

  # Characters that mark word boundaries (next letter is capitalised).
  # Default includes most punctuation: - # @ ! $ & = . + : ; _ ~ space ( ) { } [ ] | < > ? / \
  word-separators: "-#@!$&=.+:;_~ (){}[]|<>?/\\"

  # Words that should remain all-uppercase.
  initialisms:
    - ACL
    - API
    - ASCII
    - CPU
    - CSS
    - DB
    - DNS
    - EOF
    - GUID
    - HTML
    - HTTP
    - HTTPS
    - ID
    - IP
    - JSON
    - QPS
    - RAM
    - RPC
    - SLA
    - SMTP
    - SQL
    - SSH
    - TCP
    - TLS
    - TTL
    - UDP
    - UI
    - UID
    - GID
    - URI
    - URL
    - UTF8
    - UUID
    - VM
    - XML
    - XMPP
    - XSRF
    - XSS
    - SIP
    - RTP
    - AMQP
    - TS

  # Characters that get replaced with words when they appear at the start of a name.
  character-substitutions:
    "$":  DollarSign
    "-":  Minus
    "+":  Plus
    "&":  And
    "|":  Or
    "~":  Tilde
    "=":  Equal
    ">":  GreaterThan
    "<":  LessThan
    "#":  Hash
    ".":  Dot
    "*":  Asterisk
    "^":  Caret
    "%":  Percent
    "_":  Underscore
    "@":  At
    "!":  Bang
    "?":  Question
    "/":  Slash
    "\\": Backslash
    ":":  Colon
    ";":  Semicolon
    "'":  Apos
    "\"": Quote
    "`":  Backtick
    "(":  LParen
    ")":  RParen
    "[":  LBracket
    "]":  RBracket
    "{":  LBrace
    "}":  RBrace

# Name substitutions: direct overrides for specific generated names.
name-substitutions:
  # Override type names during generation.
  type-names:
    foo: MyCustomFoo  # Schema "foo" generates type "MyCustomFoo" instead of "Foo"
  # Override property/field names during generation.
  property-names:
    bar: MyCustomBar  # Property "bar" generates field "MyCustomBar" instead of "Bar"

# Import mapping: resolve external $ref targets to Go packages.
# Required when your spec references schemas from other files.
# Values can be a bare import path (alias auto-generated via hash)
# or "alias importpath" to specify an explicit import alias.
import-mapping:
  ../common/api.yaml: github.com/org/project/common
  https://example.com/specs/shared.yaml: github.com/org/shared
  # With an explicit alias:
  ../other/api.yaml: other github.com/org/project/other
  # Use "-" to indicate types should stay in the current package
  ./local-types.yaml: "-"

# Content types: regexp patterns controlling which media types generate models.
# Only request/response bodies with matching content types will have types generated.
# Default: JSON types only.
content-types:
  - "^application/json$"
  - "^application/.*\\+json$"
  # Add custom patterns as needed:
  # - "^application/xml$"
  # - "^text/plain$"

# Content type short names: maps short names to lists of content type regexp patterns.
# Used in generated type names (e.g., "FindPetsJSONResponse").
# Default: matches the content-types patterns above.
content-type-short-names:
  JSON:
    - "^application/json$"
    - "^application/.*\\+json$"
  Form:
    - "^application/x-www-form-urlencoded$"
  # Add custom short names as needed:
  # XML:
  #   - "^application/xml$"
  #   - "^application/.*\\+xml$"
  #   - "^text/xml$"

# Struct tags: controls which struct tags are generated and their format.
# Uses Go text/template syntax with a simple 2-field context (.FieldName, .IsOptional).
# Default: json and form tags with omitempty for optional fields.
# User tags are merged by name: matching defaults are overridden, new tags are appended.
# Extension-driven concerns (omitzero, json-ignore, omitempty overrides) are handled
# automatically as post-processing — templates only need the simple context.
struct-tags:
  tags:
    # Add additional tags (json and form defaults are kept):
    - name: yaml
      template: '{{ .FieldName }}{{if .IsOptional}},omitempty{{end}}'
    - name: db
      template: '{{ .FieldName }}'
    # Can override the default json template too:
    # - name: json
    #   template: '{{ .FieldName }}'

Struct tag template variables