【Spring Boot】快速整合Swagger

一、引言

swagger是当下较流行的生成Api文档的工具，在实际开发过程中，前后端开发基于Api文档来进行对接联调，而有一个好的Api文档对提升工作效率至关重要。大多数程序员是不太喜欢写文档的，比如我，而swagger很好地帮助我们解决了这个问题，通过一些简单配置，就可以帮助开发人员生成Api文档，接下来介绍Spring Boot工程如何来快速整合Swagger。

二、快速整合

这里我使用的Spring Boot版本：2.5.14

2.1 pom引入swagger依赖

在pom文件中引入swagger依赖，这里使用版本2.7.0，如下

<!-- 整合swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

2.2 定义配置类

配置类上添加注解@EnableSwagger2，说明启用swagger，配置类示例如下

/**
 * Description: SwaggerConfiguration
 * Created by kamier on 2022/12/28 22:06
 */

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    /**
     * 文档定义
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)  // 文档类型
                .apiInfo(apiInfo()) // api信息
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.kamier.springboot.swagger")) // 选择基础路径来需要生成api
                .paths(PathSelectors.any()) // 匹配某些路径，比如/user/*
                .build()
                .globalOperationParameters(setHeaderToken());   // 添加全局参数

    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("action-swagger")
                .description("api文档1")
                .termsOfServiceUrl("")
                .version("1.0")
                .build();
    }

    /**
     * 设置swagger文档中全局参数
     */
    private List<Parameter> setHeaderToken() {
        List<Parameter> params = new ArrayList<>();
        ParameterBuilder parameterBuilder = new ParameterBuilder();
        Parameter parameter = parameterBuilder.name("token")
                .description("用户token")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(true)
                .build();
        params.add(parameter);
        return params;
    }
}

2.3 编写Controller、实体类

编写一个简单Controller，用于测试，代码如下

@Api(tags = "测试api")
@RestController
@RequestMapping("/swagger")
public class SwaggerController {

    @ApiOperation("测试接口1")
    @PostMapping("/test")
    R<User> testSwagger(@RequestBody User user) {
        User user1 = new User()
                .setName("zhangsan")
                .setAge(25)
                .setStudent(false)
                .setSex(1)
                .setTel("138xxxxxxxx");
        return R.ok(user1);
    }
}

这里的@Api和@ApiOperation是swagger的注解，用以描述接口信息，并且可以看到接口的参数和返回值都用到了User类，User类代码如下

@Data
@Accessors(chain = true)
@ApiModel("用户实体")
public class User {
    @ApiModelProperty(value = "姓名", notes = "笔记", required = true)
    private String name;

    @ApiModelProperty(value = "年龄")
    private int age;

    @ApiModelProperty(value = "性别 1男 2女")
    private int sex;

    @ApiModelProperty(value = "是否学生")
    private boolean isStudent;

    @ApiModelProperty(value = "手机号", hidden = true)
    private String tel;
}

@ApiModel和@ApiModelProperty也是swagger的注解，用于描述实体以及实体属性。

2.4 项目启动

至此，一个最简单的Spring Boot整合swagger的样例就完成了。

接下来我们来启动项目（Spring Boot版本如果在2.6.x及以上，可能启动过程中会报 "Failed to start bean 'documentationPluginsBootstrapper'"异常，将Spring Boot版本改为2.5.x及以下即可），启动之后访问http://localhost:8081/swagger-ui.html，如果访问出现404，可以在WebMvcConfigurer中添加静态资源处理，代码如下

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        // 这个是后面切换ui界面的时候使用的
        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
    }
}

访问成功的页面如下

点开/swagger/test这个接口，可以看到如下页面

1. header中的token是我们在SwaggerConfiguration中配置的全局参数，所有接口的请求头都会带上这个token
2. 点击返回值和参数的Model按钮，可以看到实体的属性名称、类型及说明，前端开发根据这个就可以知道接口需要的参数或接口所要返回的数据是什么样的

2.5 UI替换

swagger自身的这种ui界面风格不太直观，在我们平时工作中，用的是另外一种界面，我们只需要引入一个依赖即可，如下

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

引入之后，重新启动项目，访问http://localhost:8081/doc.html，页面如下

到这里，整个swagger的快速整合就全部结束了