springdoc-openapi 帮助使用Spring Boot项目自动化API文档的生成。springdoc-openapi的工作原理是在运行时检查应用程序，根据Spring配置、类结构和各种注释推断API语义。
自动生成JSON/YAML和HTML格式的API文档。这个文档可以通过使用swagger-api注解来完成。
官方网站：springdoc.org
由于Spring Boot 3使用的是Jakarta EE 9，对应的springdoc版本需要升级到v2,目前里程碑M2版本。支持以下内容：
- OpenAPI 3
- Spring-boot v3 (Java 17 & Jakarta EE 9)
- JSR-303 特别注解 @NotNull, @Min, @Max, 和 @Size.
- Swagger-ui
- OAuth 2
- GraalVM native images
Swagger2已经在17年停止维护了，取而代之的是 Swagger3（基于OpenAPI 3),OpenApi是业界真正的 api 文档标准，其是由 Swagger 来维护。
这是一个基于社区的项目，不是由Spring Framework贡献者(Pivotal)维护的。
一、快速开始
为了集成spring-boot和swagger-ui，将下列依赖添加到你项目即可(不需要额外的配置)。
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.0.0-M2</version>
</dependency>
这样自动将swagger-ui部署到一个spring-boot应用程序:
1、 使用官方的swagger-uijar，可以获得HTML格式的文档；
2、 SwaggerUI页面地址http://server:port/context-path/swagger-ui.html，OpenAPI描述将在以下json格式的url上可用:http://server:port/context-path/v3/api-docs；
例如：http://localhost:8080/swagger-ui.html http://localhost:8080/v3/-api-docs
1、 文档也可以以yaml格式提供，位于以下路径:/v3/api-docs.yaml；
对于HTML格式的swagger文档的自定义路径，在spring-boot配置文件中添加一个自定义springdoc属性:。
springdoc.swagger-ui.path=/swagger-ui.html
二、Springdoc-openapi模块
Spring WebMvc支持
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
<version>2.0.0-M2</version>
</dependency>
Spring WebFlux 支持
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
<version>2.0.0-M2</version>
</dependency>
三、Restful Api服务集成
本节已Spring Boot3 Restful Api服务为例集成。
1、 在原有项目基础上加入SpringDocwebmvc依赖；
2、 启动项目；
3、 访问http://localhost:8080/swagger-ui/index.html；
基础配置
1.接口文档全局基础信息配置。
/**
* spring doc配置
*/
@Configuration
public class SpringDocConfig {
@Bean
public OpenAPI restfulOpenAPI() {
return new OpenAPI()
.info(new Info().title("Spring Boot3 Restful Zoo API")
.description("Zoo & Animal Detail APi")
.version("v0.0.1")
.license(new License().name("Apache 2.0").url("http://springdoc.org")))
.externalDocs(new ExternalDocumentation()
.description("SpringDoc Wiki Documentation")
.url("https://springdoc.org/v2"));
}
}
2.重启项目，接口文档展示具体的描述以及开源协议和wiki地址。
3.接口描述和字段描述
默认情况下接口的功能描述和参数以及字段描述都为空，需要添加对应的注解SpringDoc才能解析：
在swagger2中SpringFox项目使用非常广泛，它也是让spring boot项目快速的集成swagger。目前此项目已经停止更新。那么他们直接注解的对应关系如下：
@Api → @Tag
@ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
@ApiImplicitParam → @Parameter
@ApiImplicitParams → @Parameters
@ApiModel → @Schema
@ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)
@ApiModelProperty → @Schema
@ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")
@ApiParam → @Parameter
@ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")
下面已ZooController为例：
@Tag 描述整个Controller
@Tag(name = "ZooController", description = "动物园API")
@RestController
@RequestMapping("/zoos")
public class ZooController {
}
@Operation描述具体接口信息，@Parameter描述参数信息 @ApiResponse 接口响应描述信息
//描述具体接口信息，参数信息
@Operation(summary = "获取动物园详情", description = "返回单个对象",
parameters = {
@Parameter(name = "id", description = "动物园id")})
@ApiResponse(responseCode = "2xx",description = "动物园实体对象")
@SneakyThrows
@GetMapping(value = "/{id}")
public ResponseEntity<ZooResponse> detail(@PathVariable("id") Integer id) {
return ResponseEntity.ok(zooService.detail(id));
}
@Schema 描述对象信息
@Data
@NoArgsConstructor
@AllArgsConstructor
@Schema(name = "ZooResponse", title = "动物园对象")
public class ZooResponse implements Serializable {
@Schema(title = "动物园id")
private Integer id;
@Schema(title = "动物园名称")
private String name;
@Schema(title = "动物园地址")
private String address;
@Schema(title = "动物园电话")
private String telephone;
}
总结
SpringDoc集成Swagger到Spring Boot3 非常的方便，目前2者都是m2版本，等待最终GA版本。