How to create a link in OpenAPI 3.0 with Springdoc?

user_7519419 0
Viewed 2234

I am trying to create a link for a response in OpenAPI 3.0 specification. More specifically, I want to provide a known relationship between one of my responses and other available operation (cf. Link Object).

In my Spring Boot project I am using Springdoc (version: 1.3.9) for the generation of my API documentation. According to the @ApiResponse#links documentation I have tried to achieve my goal with following code for the endpoint:

@GetMapping(value = "/avatar", produces = MediaType.APPLICATION_JSON_VALUE)
@Operation(summary = "Request avatar info", operationId = "requestAvatar")
@ResponseStatus(HttpStatus.OK)
@ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "OK", links = {
                @Link(name = "Download Avatar", operationId = "downloadAvatar",
                        parameters = {
                                @LinkParameter(name = "userId"),
                                @LinkParameter(name = "uuid")
                        })
                }),
                ...
@ResponseBody
ResponseEntity<Avatar> requestAvatar();

Unfortunately, I cannot see any results in the Swagger UI but "No links" description.

No links

After checking the generated JSON specification I also didn't find any links key for the requestAvatar API.

Did I missed something during the creation of the @Link or does Springdoc not support the links yet?

springdoc swagger-ui openapi spring-boot java
1 Answers

Looks like linking doesn't work when @ApiResponses is used. This may be a bug.

When the responses list is defined inside @Operation, the API specification is generated correctly.

Example:

...
@Operation(summary = "Request avatar info", operationId = "requestAvatar", responses = {
        @ApiResponse(responseCode = "200", description = "OK", links = {
                @Link(name = "Download Avatar", operationId = "downloadAvatar", parameters = {
                        @LinkParameter(name = "userId", expression = "$request.query.userId"),
                        @LinkParameter(name = "uuid", expression = "$request.query.uuid")
                })
        })
})
...

Generated API specification:

...
"get": {
    "summary": "Request avatar info",
    "operationId": "requestAvatar",
    "responses": {
        "200": {
            "description": "OK",
            "content": {
                ...
            },
            "links": {
                "Download Avatar": {
                    "operationId": "downloadAvatar",
                    "parameters": {
                        "userId": "$request.query.userId",
                        "uuid": "$request.query.uuid"
                    }
                }
            }
        }
    }
}
...
user_82532090
Related