SpringBoot整合Swagger3.0

一、导入依赖

这里以springfox来使用：SpringFox是 spring 社区维护的一个项目（非官方），帮助使用者将 swagger2 集成到 Spring 中。常常用于 Spring 中帮助开发者生成文档，并可以轻松的在spring boot中使用。

swagger3只需要导入一个依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

二、配置类编写

@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket desertsApi(){
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.atxins.controller"))
                .paths(PathSelectors.any())
                .build()
                .groupName("default")
                .enable(true);
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("微服务（GMS） API说明文档")
                .description("微服务（GMS） API说明文档")
                .contact(new Contact("GMS", "https://blog.csdn.net/Achard_Wang", "787579251@qq.com"))
                .termsOfServiceUrl("https://www.zybuluo.com/mdeditor#2281023-full-reader")
                .version("1.0")
                .build();
    }
}

对应配置的结果：

注意：desertsApi() 的apis修改为自己的controller的包路径

注意：

SpringBoot更新到2.6.0启动报错 Failed to start bean ‘documentationPluginsBootstrapper‘ 问题处理

原因：Spring Boot 2.6.0开始使用基于PathPatternParser的路径匹配，而Springfox版本一直没有更新还是使用的AntPathMatcher导致了这个问题。

解决：修改yaml文件，将SpringBoot路劲匹配模式修改为AntPathMatcher就可以了，配置如下：

spring:
  mvc:
    pathmatch:
      matching-strategy: ANT_PATH_MATCHER

三、基本使用

浏览器访问Swagger UI即可访问到初始页面

四、常用注解

swagger3的注解与swagger2相差很多，也兼容了swagger2的注解，区别如下：

标注在实体类上：

@Data
@ApiModel(value = "用户类",description = "用户")
public class User {
    @Schema(description = "用户名")
    private String username;
    @Schema(description = "密码")
    private String password;
}

标注在控制器上：

@RestController
@Api(tags = "用户信息处理")
public class HelloController {
    @GetMapping("/user")
    @Operation(summary = "获取用户信息")
    @ApiImplicitParams({@ApiImplicitParam(name = "username", value = "用户名"),
            @ApiImplicitParam(name = "password", value = "密码")})
    public User getUser(@RequestParam("username")String username, @RequestParam("password")String password){
        User user = new User();
        user.setUsername(username);
        user.setPassword(password);
        return user;
    }
}

这里的@Paramters和@Parameter注解不生效，原因未知。

五、使用knife4j优化体验

1.导入依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

2.访问

直接访问http://localhost:8888/doc.html

导出文档：

文档为：

六、参考博客

Swagger3 注解使用（Open API 3）

Swagger3配置

Spring Boot 中使用 SpringFox 整合 Swagger 3（OpenAPI 3）生成 API 文档