Oapi Codegen Configuration

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "Configuration files for oapi-codegen",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "package": {
      "type": "string",
      "description": "Go package name to generate the code under"
    },
    "generate": {
      "type": "object",
      "additionalProperties": false,
      "description": "Generate specifies which supported output formats to generate",
      "properties": {
        "iris-server": {
          "type": "boolean",
          "description": "IrisServer specifies whether to generate iris server boilerplate"
        },
        "chi-server": {
          "type": "boolean",
          "description": "ChiServer specifies whether to generate chi server boilerplate"
        },
        "fiber-server": {
          "type": "boolean",
          "description": "FiberServer specifies whether to generate fiber server boilerplate"
        },
        "fiber-v3-server": {
          "type": "boolean",
          "description": "FiberV3Server specifies whether to generate fiber-v3 server boilerplate"
        },
        "echo-server": {
          "type": "boolean",
          "description": "EchoServer specifies whether to generate echo server boilerplate"
        },
        "echo5-server": {
          "type": "boolean",
          "description": "Echo5Server specifies whether to generate echo v5 server boilerplate"
        },
        "gin-server": {
          "type": "boolean",
          "description": "GinServer specifies whether to generate gin server boilerplate"
        },
        "gorilla-server": {
          "type": "boolean",
          "description": "GorillaServer specifies whether to generate Gorilla server boilerplate"
        },
        "std-http-server": {
          "type": "boolean",
          "description": "StdHTTPServer specifies whether to generate stdlib http server boilerplate"
        },
        "strict-server": {
          "type": "boolean",
          "description": "Strict specifies whether to generate strict server wrapper"
        },
        "client": {
          "type": "boolean",
          "description": "Client specifies whether to generate client boilerplate"
        },
        "models": {
          "type": "boolean",
          "description": "Models specifies whether to generate type definitions"
        },
        "embedded-spec": {
          "type": "boolean",
          "description": "EmbeddedSpec indicates whether to embed the swagger spec in the generated code"
        },
        "server-urls": {
          "type": "boolean",
          "description": "Generate types for the `Server` definitions' URLs, instead of needing to provide your own values"
        }
      }
    },
    "compatibility": {
      "type": "object",
      "additionalProperties": false,
      "description": "",
      "properties": {
        "old-merge-schemas": {
          "type": "boolean",
          "description": "In the past, we merged schemas for `allOf` by inlining each schema within the schema list. This approach, though, is incorrect because `allOf` merges at the schema definition level, not at the resulting model level. So, new behavior merges OpenAPI specs but generates different code than we have in the past. Set OldMergeSchemas to true for the old behavior. Please see https://github.com/oapi-codegen/oapi-codegen/issues/531"
        },
        "old-allof-sibling-merging": {
          "type": "boolean",
          "description": "In the past, when a schema combined `allOf` with sibling fields at the same level (`properties`, `required`, `additionalProperties`, `description`), those siblings were silently discarded and the schema was emitted as a Go type alias to its sole `allOf` target. New behavior merges the parent's siblings with the `allOf` members so the generated type carries every field declared in the spec. This is a more accurate translation of OpenAPI semantics, but it changes the shape of generated types: a schema that previously produced `type X = Y` may now produce a distinct struct embedding Y with extra fields, which is not interchangeable with Y in downstream Go code. Set OldAllOfSiblingMerging to true to restore the prior behavior. Please see https://github.com/oapi-codegen/oapi-codegen/issues/697"
        },
        "old-enum-conflicts": {
          "type": "boolean",
          "description": "Enum values can generate conflicting typenames, so we've updated the code for enum generation to avoid these conflicts, but it will result in some enum types being renamed in existing code. Set OldEnumConflicts to true to revert to old behavior. Please see: Please see https://github.com/oapi-codegen/oapi-codegen/issues/549"
        },
        "old-aliasing": {
          "type": "boolean",
          "description": "It was a mistake to generate a go type definition for every $ref in the OpenAPI schema. New behavior uses type aliases where possible, but this can generate code which breaks existing builds. Set OldAliasing to true for old behavior. Please see https://github.com/oapi-codegen/oapi-codegen/issues/549"
        },
        "disable-flatten-additional-properties": {
          "type": "boolean",
          "description": "When an object contains no members, and only an additionalProperties specification, it is flattened to a map"
        },
        "disable-required-readonly-as-pointer": {
          "type": "boolean",
          "description": "When an object property is both required and readOnly the go model is generated as a pointer. Set DisableRequiredReadOnlyAsPointer to true to mark them as non pointer. Please see https://github.com/oapi-codegen/oapi-codegen/issues/604"
        },
        "always-prefix-enum-values": {
          "type": "boolean",
          "description": "When set to true, always prefix enum values with their type name instead of only when typenames would be conflicting."
        },
        "disable-enum-value-conflict-resolution": {
          "type": "boolean",
          "description": "Turns off cross-enum value conflict resolution. By default, when two enums declare the same value, the generated constants are prefixed with their type name so they don't collide. Set this to true to disable that resolution and restore the prior behavior, in which conflict detection compared already-prefixed constant names and could miss overlaps depending on declaration order. Please see https://github.com/oapi-codegen/oapi-codegen/issues/2391"
        },
        "apply-chi-middleware-first-to-last": {
          "type": "boolean",
          "description": "Our generated code for Chi has historically inverted the order in which Chi middleware is applied such that the last invoked middleware ends up executing first in the Chi chain This resolves the behavior such that middlewares are chained in the order they are invoked. Please see https://github.com/oapi-codegen/oapi-codegen/issues/786"
        },
        "apply-gorilla-middleware-first-to-last": {
          "type": "boolean",
          "description": "Our generated code for gorilla/mux has historically inverted the order in which gorilla/mux middleware is applied such that the last invoked middleware ends up executing first in the middlewares chain This resolves the behavior such that middlewares are chained in the order they are invoked. Please see https://github.com/oapi-codegen/oapi-codegen/issues/841"
        },
        "circular-reference-limit": {
          "type": "integer",
          "description": "DEPRECATED: No longer used.\nCircularReferenceLimit allows controlling the limit for circular reference checking. In some OpenAPI specifications, we have a higher number of circular references than is allowed out-of-the-box, but can be tuned to allow traversing them."
        },
        "allow-unexported-struct-field-names": {
          "type": "boolean",
          "description": "AllowUnexportedStructFieldNames makes it possible to output structs that have fields that are unexported.\nThis is expected to be used in conjunction with an extension such as `x-go-name` to override the output name, and `x-oapi-codegen-extra-tags` to not produce JSON tags for `encoding/json`.\nNOTE that this can be confusing to users of your OpenAPI specification, who may see a field present and therefore be expecting to see it in the response, without understanding the nuance of how `oapi-codegen` generates the code."
        },
        "preserve-original-operation-id-casing-in-embedded-spec": {
          "type": "boolean",
          "description": "When `oapi-codegen` parses the original OpenAPI specification, it will apply the configured `output-options.name-normalizer` to each operation's `operationId` before that is used to generate code from.\nHowever, this is also applied to the copy of the `operationId`s in the `embedded-spec` generation, which means that the embedded OpenAPI specification is then out-of-sync with the input specificiation.\nTo ensure that the `operationId` in the embedded spec is preserved as-is from the input specification, set this. NOTE that this will not impact generated code.\nNOTE that if you're using `include-operation-ids` or `exclude-operation-ids` you may want to ensure that the `operationId`s used are correct."
        },
        "headers-implicitly-required": {
          "type": "boolean",
          "description": "Treats all response headers as required, ignoring the `required` property from the header definition. Prior to v2.6.0, oapi-codegen generated all response headers as direct values (implicitly required). The OpenAPI specification defaults headers to optional (required: false), so the corrected behavior generates optional headers as pointers. Set this to true to restore the old behavior where all headers are treated as required.\nPlease see https://github.com/oapi-codegen/oapi-codegen/issues/2267"
        },
        "enable-auth-scopes-on-context": {
          "type": "boolean",
          "description": "DEPRECATED: perform authentication and authorization at runtime using the request validation middleware instead, which evaluates the spec's security requirements directly. Please see https://github.com/oapi-codegen/oapi-codegen/issues/1524\nRe-enables the legacy emission of security scheme scopes by generated server code: the per-scheme context key types (e.g. `bearerAuthContextKey`), the scope constants (e.g. `BearerAuthScopes`), and the per-operation calls that store the operation's scopes into the request context.\nThis mechanism is off by default: it flattens the OpenAPI `security` requirements into a per-scheme list of scopes, and cannot represent alternative schemes (OR), combined schemes (AND), or anonymous (`{}`) alternatives.\nA security scheme that is a $ref into a spec covered by import-mapping does not declare its own context key type; its scopes constant is an alias of the one in the mapped package, so `context.Value` lookups use the same key across the generated packages. This requires the mapped spec's config to also set this flag. Please see https://github.com/oapi-codegen/oapi-codegen/issues/2383"
        },
        "sort-handler-registrations": {
          "type": "boolean",
          "description": "Restores the historical behavior of registering generated route handlers in sorted (lexicographic, by path then method) order. By default handlers are registered in the order their paths are declared in the spec, so that on routers which match in registration order (e.g. Fiber, Gorilla/mux) overlapping paths can be disambiguated by ordering them in the spec. Set this to true to opt out and go back to the old sorted registration order.\nPlease see https://github.com/oapi-codegen/oapi-codegen/issues/1887"
        }
      }
    },
    "output-options": {
      "type": "object",
      "additionalProperties": false,
      "description": "OutputOptions are used to modify the output code in some way",
      "properties": {
        "skip-fmt": {
          "type": "boolean",
          "description": "Whether to skip go imports on the generated code"
        },
        "skip-prune": {
          "type": "boolean",
          "description": "Whether to skip pruning unused components on the generated code"
        },
        "skip-enum-validate": {
          "type": "boolean",
          "description": "Whether to skip generation of the Valid() method on enum types"
        },
        "skip-enum-via-oneof": {
          "type": "boolean",
          "description": "Disables detection of the OpenAPI 3.1 enum-via-oneOf idiom: a schema with `type: string|integer` and `oneOf:` members that each carry `const` + `title` will normally be emitted as a Go enum with named constants. Set this to true to fall through to the standard union generator instead."
        },
        "include-tags": {
          "type": "array",
          "description": "Only include operations that have one of these tags. Ignored when empty.",
          "items": {
            "type": "string"
          }
        },
        "exclude-tags": {
          "type": "array",
          "description": "Exclude operations that have one of these tags. Ignored when empty.",
          "items": {
            "type": "string"
          }
        },
        "include-operation-ids": {
          "type": "array",
          "description": "Only include operations that have one of these operation-ids. Ignored when empty.",
          "items": {
            "type": "string"
          }
        },
        "exclude-operation-ids": {
          "type": "array",
          "description": "Exclude operations that have one of these operation-ids. Ignored when empty.",
          "items": {
            "type": "string"
          }
        },
        "user-templates": {
          "type": "object",
          "description": "Override built-in templates from user-provided files",
          "additionalProperties": {
            "type": "string"
          }
        },
        "exclude-schemas": {
          "type": "array",
          "description": "Exclude from generation schemas with given names. Ignored when empty.",
          "items": {
            "type": "string"
          }
        },
        "response-type-suffix": {
          "type": "string",
          "description": "The suffix used for responses types"
        },
        "client-type-name": {
          "type": "string",
          "description": "Override the default generated client type with the value"
        },
        "additional-initialisms": {
          "type": "array",
          "description": "AdditionalInitialisms defines additional initialisms to be used by the code generator. Has no effect unless the `name-normalizer` is set to `ToCamelCaseWithInitialisms`",
          "items": {
            "type": "string"
          }
        },
        "streaming-content-types": {
          "type": "array",
          "description": "Additional regex patterns matched against response Content-Type to decide when the strict server should generate a flush-per-chunk streaming response. Merged with the defaults (text/event-stream, application/jsonl, application/x-ndjson). Invalid regexes fail configuration validation.",
          "items": {
            "type": "string"
          }
        },
        "nullable-type": {
          "type": "boolean",
          "description": "Whether to generate nullable type for nullable fields"
        },
        "disable-type-aliases-for-type": {
          "type": "array",
          "description": "DisableTypeAliasesForType allows defining which OpenAPI `type`s will explicitly not use type aliases",
          "items": {
            "type": "string",
            "enum": ["array"]
          }
        },
        "name-normalizer": {
          "type": "string",
          "description": "NameNormalizer is the method used to normalize Go names and types, for instance converting the text `MyApi` to `MyAPI`. Corresponds with the constants defined for `codegen.NameNormalizerFunction`",
          "default": "ToCamelCase",
          "enum": [
            "ToCamelCase",
            "ToCamelCaseWithDigits",
            "ToCamelCaseWithInitialisms"
          ]
        },
        "overlay": {
          "type": "object",
          "description": "Overlay defines configuration for the OpenAPI Overlay (https://github.com/OAI/Overlay-Specification) to manipulate the OpenAPI specification before generation. This allows modifying the specification without needing to apply changes directly to it, making it easier to keep it up-to-date.",
          "properties": {
            "path": {
              "description": "The path to the Overlay file",
              "type": "string"
            },
            "strict": {
              "type": "boolean",
              "description": "Strict defines whether the Overlay should be applied in a strict way, highlighting any actions that will not take any effect. This can, however, lead to more work when testing new actions in an Overlay, so can be turned off with this setting.",
              "default": true
            }
          },
          "required": ["path"]
        },
        "yaml-tags": {
          "type": "boolean",
          "description": "Enable the generation of YAML tags for struct fields"
        },
        "client-response-bytes-function": {
          "type": "boolean",
          "description": "Enable the generation of a `Bytes()` method on response objects for `ClientWithResponses`"
        },
        "skip-client-response-content-type": {
          "type": "boolean",
          "description": "Disable the generation of a `ContentType()` method on response objects for `ClientWithResponses`, which is otherwise generated by default."
        },
        "skip-response-body-getters": {
          "type": "boolean",
          "description": "Disable the generation of `GetBody()` and `Get<TypeName>()` getter methods on response objects for `ClientWithResponses`, which are otherwise generated by default."
        },
        "prefer-skip-optional-pointer": {
          "type": "boolean",
          "description": "Allows defining at a global level whether to omit the pointer for a type to indicate that the field/type is optional. This is the same as adding `x-go-type-skip-optional-pointer` to each field (manually, or using an OpenAPI Overlay). A field can set `x-go-type-skip-optional-pointer: false` to still require the optional pointer.",
          "default": false
        },
        "prefer-skip-optional-pointer-with-omitzero": {
          "type": "boolean",
          "description": "When using `prefer-skip-optional-pointer`, generate the `omitzero` JSON tag for types that would have had an optional pointer. This is the same as adding `x-omitzero` to each field (manually, or using an OpenAPI Overlay). A field can set `x-omitzero: false` to disable the `omitzero` JSON tag.\nNOTE that this requires Go 1.24+.\nNOTE that this must be used alongside `prefer-skip-optional-pointer`, otherwise makes no difference.",
          "default": false
        },
        "prefer-skip-optional-pointer-on-container-types": {
          "type": "boolean",
          "description": "Allows disabling the generation of an 'optional pointer' for an optional field that is a container type (such as a slice or a map), which ends up requiring an additional, unnecessary, `... != nil` check. A field can set `x-go-type-skip-optional-pointer: false` to still require the optional pointer.",
          "default": false
        },
        "resolve-type-name-collisions": {
          "type": "boolean",
          "description": "When set to true, automatically renames types that collide across different OpenAPI component sections (schemas, parameters, requestBodies, responses, headers) by appending a suffix based on the component section. Also detects collisions between component types and client response wrapper types. Without this, the codegen will error on duplicate type names, requiring manual resolution via x-go-name.",
          "default": false
        },
        "generate-types-for-anonymous-schemas": {
          "type": "boolean",
          "description": "When true, every inline schema that would otherwise generate as an anonymous Go struct is instead emitted as a named type with a path-derived name (e.g. `GetRolesIdResponseBody_Data`). Equivalent to adding `x-go-type-name` to every inline schema; when both are present at the same site, `x-go-type-name` wins. Default false. The hoisted named types are declared by the same emission path that `generate.models` controls; in a single-config setup, this flag is only effective when `generate.models: true` is also set in the same config — otherwise the generated client/server code will reference type names that no emission path declares, and `go build` will fail. In a multi-config setup where one config emits `models` and a sibling emits a client or server framework into the same Go package, the flag must be set consistently across all configs; the sibling config that does not emit `models` will produce a codegen-time warning noting that it does not declare the hoisted names, which can be safely ignored when a sibling config will. See https://github.com/oapi-codegen/oapi-codegen/issues/1139",
          "default": false
        },
        "type-mapping": {
          "type": "object",
          "additionalProperties": false,
          "description": "TypeMapping allows customizing OpenAPI type/format to Go type mappings. User-specified mappings are merged on top of the defaults, so you only need to specify the types you want to override.",
          "properties": {
            "integer": {
              "$ref": "#/$defs/format-mapping"
            },
            "number": {
              "$ref": "#/$defs/format-mapping"
            },
            "boolean": {
              "$ref": "#/$defs/format-mapping"
            },
            "string": {
              "$ref": "#/$defs/format-mapping"
            }
          }
        }
      }
    },
    "import-mapping": {
      "type": "object",
      "additionalProperties": {
        "type": "string",
        "description": "ImportMapping specifies the golang package path for each external reference. A value of `-` will indicate that the current package will be used"
      }
    },
    "additional-imports": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "alias": {
            "type": "string"
          },
          "package": {
            "type": "string"
          }
        },
        "required": ["package"]
      },
      "description": "AdditionalImports defines any additional Go imports to add to the generated code"
    },
    "output": {
      "type": "string",
      "description": "The filename to output"
    }
  },
  "required": [
    "package",
    "output"
  ],
  "$defs": {
    "simple-type-spec": {
      "type": "object",
      "additionalProperties": false,
      "description": "Specifies a Go type and optional import path",
      "properties": {
        "type": {
          "type": "string",
          "description": "The Go type to use (e.g. \"int64\", \"time.Time\", \"github.com/shopspring/decimal.Decimal\")"
        },
        "import": {
          "type": "string",
          "description": "The Go import path required for this type (e.g. \"time\", \"encoding/json\")"
        }
      },
      "required": [
        "type"
      ]
    },
    "format-mapping": {
      "type": "object",
      "additionalProperties": false,
      "description": "Maps an OpenAPI type's formats to Go types",
      "properties": {
        "default": {
          "$ref": "#/$defs/simple-type-spec",
          "description": "The default Go type when no format is specified or the format is unrecognized"
        },
        "formats": {
          "type": "object",
          "description": "Format-specific Go type overrides (e.g. \"int32\": {\"type\": \"int32\"}, \"double\": {\"type\": \"float64\"})",
          "additionalProperties": {
            "$ref": "#/$defs/simple-type-spec"
          }
        }
      }
    }
  }
}