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

Posted 2023-03-10

【中文标题】如何使用 Springdoc 在 OpenAPI 3.0 中创建链接？

【英文标题】：How to create a link in OpenAPI 3.0 with Springdoc?

【发布时间】：2020-08-30 16:12:50

【问题描述】：

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

在我的 Spring Boot 项目中，我使用 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 用户界面中看不到任何结果，只有“无链接”描述。

检查生成的 JSON 规范后，我也没有找到任何 links 的 requestAvatar API 键。

我在创建@Link 的过程中是否遗漏了什么，或者 Springdoc 还不支持这些链接？

【参考方案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"
                    
                
            
        
    

...

【讨论】：

在@Operation 中声明响应适用于链接。谢谢你:)