OpenAPITools / OpenAPITools/openapi-generator
[REQ] Add externalDocs to @Operation
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.
I'm using the openapi-generator-maven-plugin 6.2.1 and its spring-boot library with springdoc-openapi-ui 1.6.6.
I'm configuring an externalDocs at operation level like below in a openapi specification file v3.0.3:
paths:
/hello/{name}:
get:
description: "Say Hello to somebody"
externalDocs:
url: "https://wiki.mycompany.com"
description: "API Wiki Specification"
operationId: hello
The url and description are used in the generated javadoc:
/**
* GET /hello/{name}
* Say Hello to somebody
*
* @param name The person's name (required)
* @return The greeting (status code 200)
* API Wiki Specification
* @see <a href="https://wiki.mycompany.com"> Documentation</a>
*/
@Operation(
operationId = "hello",
responses = {
@ApiResponse(responseCode = "200", description = "The greeting", content = {
@Content(mediaType = "application/json", schema = @Schema(implementation = MessageResource.class))
})
}
)
@RequestMapping(
Describe the solution you'd like
I would like a @ExternalDocumentation will be generated:
@Operation(
operationId = "hello",
externalDocs = @ExternalDocumentation(
description = "API Wiki Specification",
url = "https://wiki.mycompany.com"
),
responses = {
@ApiResponse(responseCode = "200", description = "The greeting", content = {
@Content(mediaType = "application/json", schema = @Schema(implementation = MessageResource.class))
})
}
)
@RequestMapping(
Thus Springdoc could add an external link:

Describe alternatives you've considered
N/A
Additional context
This requirement looks like the issue https://github.com/OpenAPITools/openapi-generator/issues/13994 for the description value of the @Operation.
If you want, I could try to contribute on this feature.
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 with the openapi-generator-maven-plugin's spring-boot generator and the code path that emits the generated @Operation annotation. Compare the existing operation description and generated Javadoc handling with the externalDocs data in the supplied OpenAPI example; done means the annotation includes the requested @ExternalDocumentation values and generation coverage verifies it.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, openapi, spring-boot
- Domain
- api, tooling
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100