openapi-codegen: support components.headers

[magdzikk]

Add support for $ref pointing to components.headers (previously it supported only parameters).

A response header written as $ref: '#/components/headers/Foo' passed ref validation and then failed at generation with IllegalStateException: Response component #/components/headers/Foo is referenced but not found.

Fixing this now, as it will happen more often when we add support for reusable headers (#1411, #5478).

Documents that do not use components.headers are unaffected.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds first-class support for components.headers in the OpenAPI model layer, including parsing, merging, reference resolution, and endpoint generation coverage.

Changes:

• Extend OpenapiComponent to include headers and parse them from OpenAPI components.
• Resolve OpenapiHeaderRef against components.headers (with fallback to components.parameters) and merge headers in OpenApiMerger.
• Add tests for parsing, ref resolution, merging behavior, and endpoint generation for referenced headers.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
openapi-codegen/core/src/main/scala/sttp/tapir/codegen/openapi/models/OpenapiComponent.scala	Adds headers to OpenapiComponent and parses/re-keys components.headers entries.
openapi-codegen/core/src/main/scala/sttp/tapir/codegen/openapi/models/OpenapiModels.scala	Updates header ref resolution to check components.headers before components.parameters.
openapi-codegen/core/src/main/scala/sttp/tapir/codegen/OpenApiMerger.scala	Merges components.headers across documents with left-biased conflict resolution.
openapi-codegen/core/src/test/scala/sttp/tapir/codegen/models/ModelParserSpec.scala	Adds parser and resolution tests for components.headers and header refs.
openapi-codegen/core/src/test/scala/sttp/tapir/codegen/PackageReuseSpec.scala	Adds merger test coverage for components.headers.
openapi-codegen/core/src/test/scala/sttp/tapir/codegen/EndpointGeneratorSpec.scala	Adds generator test verifying response header generation from components.headers refs.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.