Summary

Fixes #1411 by adding support for reusable parameters and headers.

Previously, a parameter shared across many endpoints was serialised in full into every operation, generating a lot of repetition.

How should we mark a parameter as reusable?

Option 1 - considered but rejected

For schemas, we consider it reusable if it has a name. But for parameters, they always have a name, so this approach wouldn't work.

Option 2 - considered but rejected

We could add a config opt-in flag to automatically detect duplicated parameters.

Rejected because:

• it guesses the user intent, and it might guess it wrong (it could deduplicate unrelated parameters, causing confusion)

Option 3, applied here - explicit marker

This PR adds an explicit marker:

import sttp.tapir.docs.openapi.ReusableComponentAttribute._

val tenantId = query[String]("tenantId").description("The tenant").validate(...).reusableComponent

Every operation using it then emits $ref: '#/components/parameters/tenantId', with one definition under components.parameters.

Advantages of this approach:

• consistency with the pattern in DocsExtensionAttribute (the marker is a docs/openapi-docs-owned AttributeKey, so no core change, so no MiMa surface
• request headers come along for free: OpenAPI models them as parameters with in: header, and tapir already routes them through the same collector.

This PR also adds support for response headers, which are built a bit differently, as a Header object in a separate collector. However we use the same marker for them, so that it's consistent from the user point of view.

Remarks:

1. If two explicitly marked components derive the same key, that's a bug, so generation always fails - there's no option to disambiguate with a numeric suffix, as a name like tenantId1 means nothing to whoever reads the spec. The fix is an explicit key: .reusableComponent("MyName"). (For schemas it's different, because they're not marked explicitly - hence failOnDuplicateSchemaName.)

2. Marking is per use site: query[String]("tenantId") is inlined, query[String]("tenantId").reusableComponent is referenced. Marked parameters which generate the same OpenAPI parameter share a single component, so the same parameter defined in two places is emitted once.

3. The marker is only available on what OpenAPI can lift into components: a query, path or cookie parameter, and a header - request or response. It doesn't compile on anything else; bodies in particular are already reused through components/schemas when their schema is named.

4. Tapir's own openapi-codegen previously did not read components.headers at all - fixed separately in openapi-codegen: support components.headers #5476.