OpenAPITools / OpenAPITools/openapi-generator
[REQ] [JavaSpring] Header based API operation versioning
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 26.8k
- Forks
- 7.7k
- PR merge metrics
- PR metrics pending
Description
Is your feature request related to a problem? Please describe.
We would like version the behavior of an API operation, for which the desired distinction was decided to be sent via
an API header, but the latest server generator does not generate the header parameter for the RequestMapping annotation, thus
Spring cannot distinguish between the different version implementations.
...
@Operation(
operationId = "getSomeTag",
tags = { "SomeTag" },
responses = {
@ApiResponse(responseCode = "200", description = "OK")
}
)
@RequestMapping(
method = RequestMethod.GET,
value = "/some/dummy/endpoint",
this does not get generated into the class --> headers = { "v2HeaderParam" }
)
default ResponseEntity<SomeTagV2> getSomeTagV2(...)
...
@Operation(
operationId = "getSomeTag",
tags = { "SomeTag" },
responses = {
@ApiResponse(responseCode = "200", description = "OK")
}
)
@RequestMapping(
method = RequestMethod.GET,
value = "/some/dummy/endpoint"
)
default ResponseEntity<SomeTag> getSomeTag(...)
...
Describe the solution you'd like
Change the Api.mustache template to include required header parameters into the RequestMappings annotation.
To achieve this the CodegenOperationModel members have to be aligned to contain the required headers too (currently there are only members for headers and required parameters, which are not eligible for the template controls).
Describe alternatives you've considered
Using Api versioning or a different resource is for some use cases not an option.
Additional context
N/A
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by locating the Api.mustache template and the CodegenOperationModel members used by its template controls. Trace how header parameters and required parameters reach the JavaSpring generator, then verify that required headers appear in generated RequestMapping annotations so versioned operations can be distinguished.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, spring
- Domain
- api, backend, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100