【SpirngBoot组件（1）】Swagger集成

个人学习笔记分享，当前能力有限，请勿贬低，菜鸟互学，大佬绕道

如有勘误，欢迎指出和讨论，本文后期也会进行修正和补充

前言

使用Swagger可以方便快捷的查看和调试接口，而不再需要借助其他第三方工具（如postman），更不需要在茫茫代码中寻找接口，其相关注解也一定程度上提高了代码可读性。

因此，swagger几乎已经算的上是一个项目的必要组件了。

1.介绍

1.1.Swagger、Spring、SpringFox

Swagger是一个流行的API框架，对整个API开发周期提供解决方案，包括设计、编码和测试等等，几乎支持所有语言。
Spring作为常用的Java开发框架，不做多余叙述
SpringFox是一个基于Spring的组件，用于Swagger集成至SpringMVC，后发展至SpringFox，Springfox-swagger2则是其中一个组件
Springfox-Swagger-UI顾名思义则是一个UI组件，用于展示相关数据

总结：

Swagger是API解决方案
Spring是Java框架
SpringFox是基于Java的Swagger实现
Springfox-Swagger-UI是配套的UI

1.2.用途

前后端分离：前端只需要通过Swagger即可查找并调试接口
API整理：暴露给外部的接口全部展示在Swagger，方便查找和整理
增强代码可读性：相关注解在后端也会使代码可读性更好，相当于充当了注释的作用

2.集成

目前SpringFox已经更新至3.0版本，修复了大量问题，关键是配置方法做出了改变，故将SpringFox2与SpringFox3分开记录

2.1.swagger2（主流版本）

添加依赖

    io.springfox
    springfox-swagger2
    2.6.1



    io.springfox
    springfox-swagger-ui
    2.6.1
前者为swagger2依赖，后者为ui，后者可以更换为其他ui，此处不做多述

创建swagger配置文件

@Configuration
@EnableSwagger2
@Profile({"dev", "test"})
public class SwaggerConfig {
    @Bean // 配置docket以配置Swagger具体参数
    public Docket docket(Environment environment) {

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())// 关联配置文档
                .enable(true)// 是否启用
                .select()//扫描方法
                .apis(RequestHandlerSelectors.basePackage("com.yezi_tool.basic_project.controller"))//扫描包路径
                .paths(PathSelectors.any())//路径过滤
                .build();//构建
    }

    // 配置文档信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot-Swagger2集成")
                .description("API描述")
                .contact("联系人名字")
                .version("1.0")
                .build();
    }
}

启动项目后，打开网址http://localhost:8080/swagger-ui.html，请自行修改端口和路径

2.2.swagger3版本

添加依赖

        
            io.springfox
            springfox-boot-starter
            3.0.0

仅此一个依赖

创建swagger配置文件

@Configuration
@EnableOpenApi
@Profile({"dev", "test"})
public class Swagger3Config {
    @Bean // 配置docket以配置Swagger具体参数
    public Docket docket() {
        return new Docket(DocumentationType.OAS_30)//文档类型
                .apiInfo(apiInfo())// 关联配置文档
                .select()//扫描方法
                .apis(RequestHandlerSelectors.basePackage("com.yezi_tool.basic_project.controller"))//扫描包路径
                .paths(PathSelectors.any())//路径过滤
                .build();//构建
    }

    // 配置文档信息
    private ApiInfo apiInfo() {
        Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
        return new ApiInfo(
                "Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://terms.service.url/组织链接", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
        );
    }
}

启动项目后，打开网址http://localhost:8080/swagger-ui/index.html，请自行修改端口和路径

2.3.版本差异

swagger3进行了大量更新与修复，不做多述
swagger3仅需一个依赖，将swagger和UI合并
配置文件的注解，swagger2需要@EnableSwagger2，而swagger3需要@EnableOpenApi
配置文件的ApiInfo构造方法变更，小问题
项目默认地址变更，swagger2的地址是/swagger-ui.html，swagger3的地址是swagger-ui/index.html
部分方法改动，如2.5的全局参数

2.4.配置文件额外参数

通常上述参数已满足需求，当然还提供了其他参数供开发者选择，两个版本的自定义参数基本一致

注解@Profile：枚举适用的运行环境，通常仅在开发环境和测试环境中启用，则可使用@Profile({"dev", "test"})
配置文档信息：请根据需求修改，不做多述
docket对象方法
- enable()：是否启用swagger，参数为true/false，但通常用注解@Profile控制
- api()：指定包扫描路径，参数形如RequestHandlerSelectors.basePackage("com.test.api")，也可以根据自身需求调整，其余形式参数如下
  - RequestHandlerSelectors.any()：扫描所有，项目中的所有接口都会被扫描到
  - RequestHandlerSelectors.none() ：不扫描接口
  - RequestHandlerSelectors.withMethodAnnotation(final Class annotation)： 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
  - RequestHandlerSelectors.withClassAnnotation(final Class annotation)： 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
  - RequestHandlerSelectors.basePackage(final String basePackage) ： 根据包路径扫描接口
- paths()：指定url路径过滤，参数形如PathSelectors.ant("/login/**")，也可以根据自身需求调整，其余形式参数如下
  - PathSelectors.any()： 任何请求都扫描
  - PathSelectors.none() ： 任何请求都不扫描
  - PathSelectors.regex(final String pathRegex) ： 通过正则表达式控制
  - PathSelectors.ant(final String antPattern) ： 通过ant()控制
- groupName()：配置分组，参数为String字符串，如group 1，默认分组为default，如需设置多个分组，则实例化多个不同名的docket即可
- getGlobalOperationParameters：全局参数，不适用于swagger3，通常用于token，示例如下
```
        ParameterBuilder ticketPar = new ParameterBuilder();
        List pars = new ArrayList();
        ticketPar.name("token")
                .description("token")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .build();
        pars.add(ticketPar.build());
        docket.globalOperationParameters(pars)
```

2.5.全局参数（重点）

通常用于设置token，swagger3修改了相关方法，所以此处均给出示例

swagger2版本

  public Docket docket() {
        ...
      docket.globalOperationParameters(pars);
        ...
    }
            
    private List pars(){
        List pars = new ArrayList();
        ParameterBuilder ticketPar = new ParameterBuilder();
        ticketPar.name("token")
                .description("token")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .build();
        pars.add(ticketPar.build());
        return pars;
    }

swagger3版本

  public Docket docket() {
        ...
      docket.protocols(new LinkedHashSet<>(Arrays.asList("https", "http")))// 支持的通讯协议集合
        .securitySchemes(securitySchemes())// 授权信息设置，必要的header token等认证信息
        .securityContexts(securityContexts());// 授权信息全局应用
        ...
    }
    /**
     * 设置授权信息
     */
    private List securitySchemes() {
        return Collections.singletonList(new ApiKey("BASE_TOKEN", "token", "pass"));
    }

    /**
     * 授权信息全局应用
     */
    private List securityContexts() {
        return Collections.singletonList(
                SecurityContext.builder().securityReferences(Collections.singletonList(new SecurityReference("BASE_TOKEN", new AuthorizationScope[]{new AuthorizationScope("global", "")}))).build());
    }

3.使用

使用步骤

当然一切的前提是先集成

添加注解

实体类添加注解，实例如下

@ApiModel("登录信息实体")
public class LoginRequest {
   @ApiModelProperty("用户名")
   public String username;
   @ApiModelProperty("密码")
   public String password;
}

控制器添加注解，实例如下

@Controller
@RequestMapping("/testController")
@Api(tags = "测试")
public class TestController {
}

接口方法添加注解，实例如下

    @ApiOperation("测试swagger")
    @PostMapping("/testSwagger")
    @ResponseBody
    public LoginRequest testSwagger(@ApiParam(required = false, value = "登录实体") @RequestParam(required = false) @RequestBody LoginRequest loginRequest) throws Exception {
        if (loginRequest == null) {
            loginRequest = new LoginRequest();
        }
        return loginRequest;
    }

swagger测试，没什么好贴图的，就省了吧。。

4.传送门

Swagger2集成方案

Swagger3集成方案

SpringFox官方主页

BB两句

为啥总感觉swagger3变丑了好多。。。

作者：Echo_Ye

WX：Echo_YeZ

email ：[email protected]

个人站点：在搭了在搭了。。。（右键 - 新建文件夹）