Spring Boot RESTful API Open API (Swagger) 文档标注 (Annotation)

我们可以通过给 Spring Boot 项目增加以下的依赖项来给 RESTful 控制器 (Controllers) 增加 Open API 文档页面，但是这只解决了有没有的问题，那么我们如何给每一个 REST API 增加更详细的说明呢？

REST 方法

简单来说我们可以使用 @Operation 标注, @Parameter 标注以及 @ApiResponses 标注来给我们的每个 API 增加更详细的说明，具体示例如下：

@DeleteMapping("{id}")
@Operation(description = "删除指定的 Customer 记录")
@ApiResponses(
        value = {
                @ApiResponse(responseCode = "404", description = "不能找到指定 ID 的 Customer 记录"),
                @ApiResponse(responseCode = "200", description = "成功删除了指定 ID 的 Customer 记录")
        }
)
public void deleteCustomer(
        @Parameter(description = "要删除的 Customer 的 ID")
        @PathVariable Integer id) {
    try {
        var result = this.customerService.findCustomerById(id);
    } catch (NotFoundException e) {
        throw new ResponseStatusException(HttpStatus.NOT_FOUND, e.getMessage());
    }

    this.customerService.deleteCustomer(id);
}

以下是加上了注释的 Open API 页面的样子：

如果我们注释掉@Operation, @ApiResponses, @Parameter 这些文档标注，它是这个样子的：

返回类

我们可以使用 @Schema 来给返回类来加上备注，例如：

public class NodeData {
    @Schema(example = "1000086", required = true, description = "节点ID")
    @NotNull
    private int id;

    @NotBlank
    private String code;

    @NotBlank
    private String name;

    private String description;

    private List<NodeData> Children;
}

总结

本文介绍了给 Spring Boot API 增加详细文档的3个标注 @Operation, @ApiResponses, @Parameter，以及给我们的类做标注的 @Schema。增加这些标注有助于 API 的使用者更好地理解如何使用我们的 API，让我们的 API 更容易使用。

参考链接：

本文所展示的源码
给Spring Boot增加open API文档支持
https://www.baeldung.com/spring-rest-openapi-documentation