Parse declared response headers into typed fields on client response wrappers (oapi-codegen#2462)

Closes: oapi-codegen#2011

Response headers declared in the spec were dropped by the generated
client: the response wrapper exposed only the body fields, leaving
declared headers reachable solely through the raw http.Response. The
strict server already generates typed header structs and writes them in
its Visit* methods; the client had no equivalent on the read side.

Each response that declares headers now generates a client-local struct
named after the response wrapper (e.g. GetFooResponse200Headers), and
the wrapper gains a matching Headers<StatusCode> pointer field
(Headers200, HeadersDefault, ...) populated by Parse<Op>Response using
runtime.BindStyledParameterWithOptions with ParamLocationHeader
("simple" style, per the OpenAPI spec for response headers). Deriving
the type name from the wrapper (via genResponseTypeName) keeps it
collision-resolver-aware, and the types are emitted and consumed
entirely within the client output, independent of the strict server's
<Op><Status>ResponseHeaders types.

Binding is lenient: an absent header - even a required one - leaves the
field at its zero value rather than failing the parse, mirroring the
body unmarshal's tolerance of spec-violating servers; a present header
that fails to bind to its declared type is an error. Case clauses are
ordered most-specific-first (exact codes, then range wildcards, then
default) by the same lexicographic scheme the body unmarshal uses.

The change is purely additive: specs without response headers generate
byte-identical output, and no strict-server or model output changes.

Co-authored-by: Claude Fable 5 <[email protected]>

Author: mromaszewicz

internal/test/clients/responseheaders/config.yaml

@@ -0,0 +1,10 @@
+# yaml-language-server: $schema=../../../../configuration-schema.json
+# From issue-2011
+package: responseheaders
+output: headers.gen.go
+generate:
+  models: true
+  client: true
+output-options:
+  # Exercises the nullable.Nullable[T] header-binding path (IsNullable).
+  nullable-type: true

internal/test/clients/responseheaders/doc.go

@@ -0,0 +1,11 @@
+// Package responseheaders verifies that response headers declared in the
+// spec are parsed into typed Headers<StatusCode> fields on the generated
+// client response wrappers. The header structs are client-local types named
+// after the response wrapper (e.g. GetFooResponse200Headers), emitted and
+// consumed entirely within the client output; specs without response
+// headers generate no additional code.
+//
+// From issue-2011.
+package responseheaders
+
+//go:generate go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen --config=config.yaml spec.yaml