SpringBoot3整合swagger（springdoc-openapi）_springdoc-openapi-starter-webmvc-ui

一、前言

网上查看了大量资料，发现SpringBoot3+jdk17的情况下，swagger的V2和V3都是不行的。果断转用spring官方出品的springdoc-openapi。在使用springdoc-openapi的时候也有很多坑，首先springdoc-openapi的v1.x.x版本也是不行的，springdoc-openapi的版本必须是v2.x.x以上。

官网链接：https://springdoc.org/v2/

二、入门配置

1、改pom

我的示例Demo项目只引入了很简单的一些东西。下面的两个jar包，第一个是必须导入的，而且一定得在2版本以上。

        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.1.0</version>
        </dependency>

        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
            <version>2.1.0</version>
        </dependency>
1
2
3
4
5
6
7
8
9
10
11

2、写Controller案例

2.1不用其他配置

OpenApiConfig这种配置完全可以不用做，application.yml也可以完全不用配置。默认引入pom文件以后，写好Controller就可以用了。

package com.zt.controller;

import com.zt.framework.web.CommonResult;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Slf4j
@Tag(name = "hello")
public class HelloController {

    @GetMapping("/hello")
    @Operation(summary = "hello", description = "hello")
    public CommonResult<String> hello(){
        int a = 1/0;
        log.info("hello!!!");
        return CommonResult.successMessage("hello!!!");
    }

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

2.2注意注释区别

@Api -> @Tag
@ApiIgnore -> @Parameter(hidden = true) 或 @Operation(hidden = true) 或 @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")
1
2
3
4
5
6
7
8
9
10

3、检验测试

访问地址swagger-ui风格：
http://server:port/context-path/swagger-ui.html
访问地址swagger-json风格：
http://server:port/context-path/v3/api-docs

我这边个人swagger-ui风格地址：
http://localhost:8888/swagger-ui/index.html


我这边个人swagger-json风格地址：
http://localhost:8888/v3/api-docs

导入apifox也完全没问题，本身就是OpenApi3

三、加强配置

1、方式一：引入OpenApiConfig

package com.zt.framework.config;

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.media.StringSchema;
import io.swagger.v3.oas.models.parameters.Parameter;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springdoc.core.configuration.SpringDocConfiguration;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.boot.autoconfigure.AutoConfigureBefore;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.util.Collections;

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI openApi() {
        return new OpenAPI()
                .info(new Info()
                        .title("文档标题")
                        .description("文档描述")
                        .contact(new Contact().name("作者").email("邮箱").url("可以写你的博客地址或不填"))
                        .version("v2.0"));
    }

}

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
26
27
28
29
30
31
32
33
34
35

参考大神链接：https://blog.csdn.net/m88997766/article/details/130026004

这边还能配置很多东西。常见的api分组等等，参考上面大神链接。

2、方式二：配置application.yml

springdoc:
  api-docs:
    # 是否开启接口文档
    enabled: true
  swagger-ui:
    # 持久化认证数据，如果设置为 true，它会保留授权数据并且不会在浏览器关闭/刷新时丢失
    persistAuthorization: true
1
2
3
4
5
6
7

yml这边应该还有很多其他配置。详细见前言的官网说明。