前言

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

1
2
3
4
5
6
7
// 用于给 Controller 或接口分组和添加描述。
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
10
// 用于描述方法参数。
import io.swagger.v3.oas.annotations.Parameter;

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

@Parameters

1
2
3
4
5
6
7
8
9
10
11
12
// 用于描述多个参数（较少用，通常直接在参数上加 @Parameter）。
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
11
// 用于描述接口方法。
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
13
// 用于描述接口响应。
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
12
// 用于描述实体类或字段。
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
8
// 用于隐藏接口、方法或参数。
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
# acturator
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();
	}
}