如何使用 Springdoc 在 OpenAPI 3.0 中创建 link？

Question

我正在尝试为 OpenAPI 3.0 规范中的响应创建一个 link。更具体地说，我想提供我的一个响应与其他可用操作之间的已知关系（参见 Link Object）。

在我的 Spring 引导项目中，我使用 Springdoc（版本：1.3.9）生成我的 API 文档。根据 @ApiResponse#links 文档，我尝试使用以下端点代码实现我的目标：

@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();

不幸的是，我在 Swagger UI 中看不到任何结果，但是“没有 links”描述。

检查生成的 JSON 规范后，我也没有找到 requestAvatar API.

的任何 links 键

我是不是在创建 @Link 的过程中遗漏了什么，或者 Springdoc 还不支持 link 吗？

Answer 1

使用 @ApiResponses 时链接似乎不起作用。这可能是一个错误。

当在 @Operation 中定义响应列表时，正确生成 API 规范。

示例：

...
@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")
                })
        })
})
...

生成API规格：

...
"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"
                    }
                }
            }
        }
    }
}
...

如何使用 Springdoc 在 OpenAPI 3.0 中创建 link？

How to create a link in OpenAPI 3.0 with Springdoc?

java

spring-boot

swagger-ui

openapi

springdoc