Add HeadersImplicitlyRequired compatibility flag for #2267

mromaszewicz · claude · mromaszewicz · commit bf6c7692ae75 · 2026-03-26T22:02:30.000-07:00
Allows users to restore the pre-v2.5.0 behavior where all response
headers are treated as required, ignoring the OpenAPI `required` field.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/configuration-schema.json b/configuration-schema.json
@@ -115,6 +115,10 @@
         "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"
         }
       }
     },
diff --git a/pkg/codegen/configuration.go b/pkg/codegen/configuration.go
@@ -287,6 +287,16 @@ type CompatibilityOptions struct {
 	// NOTE that this will not impact generated code.
 	// NOTE that if you're using `include-operation-ids` or `exclude-operation-ids` you may want to ensure that the `operationId`s used are correct.
 	PreserveOriginalOperationIdCasingInEmbeddedSpec bool `yaml:"preserve-original-operation-id-casing-in-embedded-spec"`
+
+	// HeadersImplicitlyRequired 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.
+	// Please see https://github.com/oapi-codegen/oapi-codegen/issues/2267
+	HeadersImplicitlyRequired bool `yaml:"headers-implicitly-required,omitempty"`
 }
 
 func (co CompatibilityOptions) Validate() map[string]string {
diff --git a/pkg/codegen/operations.go b/pkg/codegen/operations.go
@@ -947,7 +947,7 @@ func GenerateResponseDefinitions(operationID string, responses map[string]*opena
 				Name:     headerName,
 				GoName:   SchemaNameToTypeName(headerName),
 				Schema:   contentSchema,
-				Required: header.Value.Required,
+				Required: header.Value.Required || globalState.options.Compatibility.HeadersImplicitlyRequired,
 				Nullable: nullable,
 			}
 			responseHeaderDefinitions = append(responseHeaderDefinitions, headerDefinition)

Original file line number	Diff line number	Diff line change
`@@ -115,6 +115,10 @@`
`115`	`115`	`"preserve-original-operation-id-casing-in-embedded-spec": {`
`116`	`116`	`"type": "boolean",`
`117`	`117`	"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."
	`118`	`+ },`
	`119`	`+ "headers-implicitly-required": {`
	`120`	`+ "type": "boolean",`
	`121`	+ "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"
`118`	`122`	`}`
`119`	`123`	`}`
`120`	`124`	`},`
Original file line number	Diff line number	Diff line change
`@@ -947,7 +947,7 @@ func GenerateResponseDefinitions(operationID string, responses map[string]*opena`
`947`	`947`	`Name: headerName,`
`948`	`948`	`GoName: SchemaNameToTypeName(headerName),`
`949`	`949`	`Schema: contentSchema,`
`950`		`- Required: header.Value.Required,`
	`950`	`+ Required: header.Value.Required \|\| globalState.options.Compatibility.HeadersImplicitlyRequired,`
`951`	`951`	`Nullable: nullable,`
`952`	`952`	`}`
`953`	`953`	`responseHeaderDefinitions = append(responseHeaderDefinitions, headerDefinition)`