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