springboot集成springdoc-openapi

一、springboot集成springdoc-openapi

1. 添加pom.xml 依赖

<!--swagger-->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.9</version>
</dependency>
1
2
3
4
5
6

2. 配置config

@OpenAPIDefinition(
        security = @SecurityRequirement(name = "Authorization")
)
@SecurityScheme(type = SecuritySchemeType.APIKEY, name = "Authorization", scheme = "Authorization", in = SecuritySchemeIn.HEADER)
@Configuration
public class OpenApiConfig {
    private String title = "SpringDoc API";
    private String description = "SpringDoc Application";
    private String version = "v0.0.1";

    @Bean
    public OpenAPI springOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title(title)
                        .description(description)
                        .version(version));
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

这里的@OpenAPIDefinition 和@SecurityScheme都是springdoc注解，主要声明API信息：标题、版本、许可证、安全性、服务器、标签、安全性和拓展文档信息。
配置jwt时，@SecurityScheme(type = SecuritySchemeType.HTTP, name = “JWT”, scheme = “bearer”, in = SecuritySchemeIn.HEADER).scheme 还支持basic。
具体可查看官网文档: https://springdoc.org/index.html

3. 配置文件中配置文档开关

springdoc:
  api-docs:
    #是否开启文档功能，默认为true，可不配置
    enabled: true
  swagger-ui:
    # 访问ip:host/api，可直接访问Swagger springdoc
    path: /api
1
2
3
4
5
6
7

4. 业务逻辑相关代码

DTO

@Data
public class CustomizedWaveDTO {

    @Schema(name = "id")
    private Long id;

    @Schema(name = "sensorId")
    private Long sensorId;

    @Schema(name = "extensionType",description = "speed->速度，accelerated->加速度...",title = "speed->速度，accelerated->加速度...")
    private String extensionType;

    @Schema(name = "waveType",description = "频谱图->2，包络分析图->3...",title = "频谱图->2，包络分析图->3...")
    private String waveType;

    @Schema(name = "lowCut",description = "滤波初始频率",title = "滤波初始频率")
    private Double lowCut;

    @Schema(name = "highCut",description = "滤波截止频率",title = "滤波截止频率")
    private Double highCut;

    @Schema(name = "bandwidth",description = "滤波宽带",title = "滤波宽带")
    private Double bandwidth;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

其中@Schema是springdoc配置接口回显数据的说明
controller

@RestController
@RequestMapping("/api/customizedWave")
@Tag(name = "自定义波形")
public class CustomizedWaveController {

    @Resource
    private CustomizedWaveService customizedWaveService;

    @RequestMapping(value = "/{id}", method = RequestMethod.GET)
    @Operation(summary = "通过id获取自定义配置", description = "通过id获取自定义配置")
    public CustomizedWaveDTO getCustomizedWave(@PathVariable("id") Long id) {
        return customizedWaveService.findById(id);
    }
1
2
3
4
5
6
7
8
9
10
11
12
13

其中@Tag就相当于原来的@Api，声明一个Controller。
@Operation就相当于原来的@ApiOperation，声明一个接口信息。

启动项目，访问localhost:8081/api

配置授权信息

但是这时候界面也是极其简陋的：

二、springdoc-openapi基础上升级为knife4j

1.在pom.xml中添加knife4j依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-springdoc-ui</artifactId>
    <version>3.0.3</version>
</dependency>
1
2
3
4
5

2. 配置config

如果你不喜欢 swagger-ui 的界面风格，会集成 knife4j 的 ui。Spring Doc 也可以集成 knife4j。
如果要使用 knife4j ，Spring Doc 的配置中需要添加分组配置，我们这里添加一个最简单的分组配置。

@Bean
public GroupedOpenApi publicApi() {
    return GroupedOpenApi.builder()
            .group(title)
            .pathsToMatch("/**")
            .build();
}
1
2
3
4
5
6
7

3. 配置文件

knife4j:
	enable: true  # 默认为true，可不配置，用上面springdoc的enable一起控制两个接口文档
1
2

4.访问knife4j接口文档

http://localhost:8081/doc.html

配置一下请求头权限就可以测试接口了