关于springboot: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的疾速整合就全副完结了