前言

SpringDoc 是一个用来自动生成 API 文档的库。它是基于 SpringBoot 项目的，遵循 OpenAPI3（一个组织规定的规范）规范。它是通过检查我们运行中的程序，推断出基于 Spring 配置、类结构和各种注解的 API 语义，从而自动生成 JSON、YAML 和 HTML 格式的接口文档。

而我们不得不提的就是 Swagger。Swagger 是一个公司的开源项目，将自己的 API 设计贡献给了 OpenAPI 并由其标准化。在 SpringDoc 之前我们还可以使用 Springfox，和 SpringDoc 一样是一个用于生成 API 文档的库，2020 年起不再更新。

官方文档链接：https://springdoc.org/#Introduction

使用

插件使用【用于生成 openapi.json】：https://springdoc.org/#plugins

官方 demo 文档：https://github.com/springdoc/springdoc-openapi-demos

访问主页：http://localhost:8080/swagger-ui.html

注解介绍

@Tag

用于给 Controller 或接口分组和添加描述。

1
2
3
4
5
6
import io.swagger.v3.oas.annotations.tags.Tag;

@Tag(name = "用户管理", description = "用户相关操作接口")
@RestController
@RequestMapping("/users")
public class UserController { ... }

@Parameter

用于描述方法参数。

1
2
3
4
5
6
7
8
9
import io.swagger.v3.oas.annotations.Parameter;

@GetMapping("/{id}")
public User getUser(
    @Parameter(description = "用户ID", required = true, example = "1")
    @PathVariable Long id
) {
    // ...
}

@Parameters

用于描述多个参数（较少用，通常直接在参数上加 @Parameter）。

1
2
3
4
5
6
7
8
9
10
11
import io.swagger.v3.oas.annotations.Parameters;
import io.swagger.v3.oas.annotations.Parameter;

@Parameters({
    @Parameter(name = "id", description = "用户ID"),
    @Parameter(name = "name", description = "用户名")
})
@GetMapping("/search")
public User searchUser(@RequestParam Long id, @RequestParam String name) {
    // ...
}

@Operation

用于描述接口方法。

1
2
3
4
5
6
7
8
9
10
import io.swagger.v3.oas.annotations.Operation;

@Operation(
    summary = "获取用户信息",
    description = "根据用户ID获取详细信息"
)
@GetMapping("/{id}")
public User getUser(@PathVariable Long id) {
    // ...
}

@ApiResponse

用于描述接口响应。

1
2
3
4
5
6
7
8
9
10
11
12
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;

@Operation(summary = "删除用户")
@ApiResponses({
    @ApiResponse(responseCode = "200", description = "删除成功"),
    @ApiResponse(responseCode = "404", description = "用户未找到")
})
@DeleteMapping("/{id}")
public void deleteUser(@PathVariable Long id) {
    // ...
}

@Schema

用于描述实体类或字段。

1
2
3
4
5
6
7
8
9
10
11
import io.swagger.v3.oas.annotations.media.Schema;

@Schema(description = "用户实体")
public class User {

    @Schema(description = "用户ID", example = "1")
    private Long id;

    @Schema(description = "用户名", nullable = true)
    private String name;
}

@Hidden

用于隐藏接口、方法或参数。

1
2
3
4
5
6
7
import io.swagger.v3.oas.annotations.Hidden;

@Hidden
@GetMapping("/internal")
public String internalApi() {
    // 该接口不会出现在文档中
}

问题记录

整合 Actuator

application.properties

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# actuator
management.server.port=9090
management.endpoint.health.show-details=always
management.endpoints.web.exposure.include=*
# management.server.port 和 server.port 使用不同端口/域的时候会出现跨域错误，这里配置允许所有 origin
management.endpoints.web.cors.allowed-origins=*

# springdoc
springdoc.version=@springdoc.version@
springdoc.swagger-ui.display-request-duration=true
springdoc.swagger-ui.groups-order=desc
springdoc.swagger-ui.operations-sorter=method
springdoc.swagger-ui.disable-swagger-default-url=true
# 访问 root 路径时会跳到 swagger ui 的路径
springdoc.swagger-ui.use-root-path=true
springdoc.cache.disabled=true
# 开启 springdoc 中显示 actuator 相关接口
springdoc.show-actuator=true

SwaggerConfig

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
@Configuration
public class SwaggerConfig {

	@Bean
	public GroupedOpenApi actuatorApi(
			WebEndpointProperties endpointProperties, @Value("${springdoc.version}") String appVersion) {
		return GroupedOpenApi.builder()
				// 默认分组名即 x-actuator，这里主要是为其分组添加标题/版本/描述等
				.group("x-actuator")
				.pathsToMatch(endpointProperties.getBasePath() + ALL_PATTERN)
				.addOpenApiCustomizer(
						openApi ->
								openApi.info(
										new Info()
												.title("Actuator API")
												.version(appVersion)
												.description("Spring Boot Actuator Endpoint documentation")))
				.build();
	}
}