下载掌阅APP，畅读海量书库
立即打开
springdoc-openapi是一个专为Spring Boot应用程序设计的开源库，旨在自动生成符合OpenAPI 3规范的文档。OpenAPI（以前称为Swagger）为描述RESTful API提供了一个标准化的框架，涵盖了API的端点、请求/响应格式、身份验证等方面。
使用springdoc-openapi可以快速、简便地生成API文档，从而促进前后端团队的无缝协作。除了文档生成，springdoc-openapi还内嵌了Swagger UI，其为开发者和用户提供了一个直观的界面来浏览和测试API。
相比传统的Swagger 2库，springdoc-openapi为OpenAPI 3提供了更全面的支持，是生成OpenAPI 3文档的首选工具。
为了在Spring Boot项目中集成springdoc-openapi，首先需要在项目的pom.xml中添加相应的依赖：
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.1.0</version>
</dependency>
当Spring Boot应用启动后，springdoc-openapi会自动执行以下操作。
扫描控制器：扫描所有带有@RestController和@Controller注解的类。
读取路由信息：分析每个控制器类及其方法上的路由信息（如@GetMapping、@PostMapping、@PutMapping等）。
参数和返回值：读取方法的参数和返回值，通常通过Java反射和相关库（如Jackson）实现。
OpenAPI注解：如果使用了OpenAPI相关注解（如@Operation、@ApiResponse、@Parameter等），也会被解析并包含在文档中。
生成文档：基于收集到的信息，生成OpenAPI 3.0+的描述文档。
默认情况下，Swagger UI可以通过http://localhost:8080/swagger-ui.html访问（假设应用运行在默认的8080端口）。这个界面允许用户查看并与API文档互动，效果如图2-2所示。
图2-2 在线API文档
OpenAPI提供了一系列注解，使得开发者可以更精确地描述API的行为、参数和响应。以下是一些常用的OpenAPI注解及其用途。
// 主应用类
@OpenAPIDefinition(info = @Info(title = "我的API", version = "v1",
description = "我的API描述"))
public class Application {
}
@RestController
@RequestMapping("/items")
public class ItemController {
// 获取所有项目
@GetMapping
@Operation(summary = "获取所有项目", description = "从仓库中获取所有项目。")
public List<Item> getItems() {
}
// 根据ID获取特定项目
@GetMapping("/{id}")
@Operation(summary = "根据ID获取项目", description = "根据ID获取特定项目。")
@ApiResponse(responseCode = "200", description = "找到了项目")
@ApiResponse(responseCode = "404", description = "未找到项目")
public Item getItem(@PathVariable @Parameter(description = "需要获取的
项目的ID") Long id) {
}
}
// 数据模型
public class Item {
@Schema(description = "项目的唯一标识符")
private Long id;
@Schema(description = "项目的名称")
private String name;
// Getter和Setter...
}
在以上代码示例中：
@OpenAPIDefinition定义了整个API的基本信息，如标题、版本和描述。
@Operation用于描述具体的API端点（如获取所有项目的操作）。
@Parameter描述了请求中的参数，如路径参数。
@ApiResponse用于描述可能的响应和它们的状态码。
@Schema定义了数据模型的结构，如用于请求和响应的数据类型。
这些注解只是OpenAPI注解的一部分。为了提高API文档的质量，可能需要结合多个注解使用。同时，尽管这些注解有助于提供更详尽的文档，但并非必须，因为springdoc-openapi默认会为API自动生成大部分文档。