【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.用途

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

2.集成

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

2.1.swagger2（主流版本）

1. 添加依赖

   <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
   </dependency>
   
   <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.1</version>
   </dependency>
   

   前者为swagger2依赖，后者为ui，后者可以更换为其他ui，此处不做多述

2. 创建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();
    }
   }
   

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

2.2.swagger3版本

1. 添加依赖

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

   仅此一个依赖

2. 创建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<>()// 扩展
        );
    }
   }
   

3. 启动项目后，打开网址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<? extends Annotation> annotation)： 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
    • RequestHandlerSelectors.withClassAnnotation(final Class<? extends Annotation> 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<Parameter> pars = new ArrayList<Parameter>();
            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<Parameter> pars(){
          List<Parameter> pars = new ArrayList<Parameter>();
          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<SecurityScheme> securitySchemes() {
          return Collections.singletonList(new ApiKey("BASE_TOKEN", "token", "pass"));
      }
  
      /**
       * 授权信息全局应用
       */
      private List<SecurityContext> securityContexts() {
          return Collections.singletonList(
                  SecurityContext.builder().securityReferences(Collections.singletonList(new SecurityReference("BASE_TOKEN", new AuthorizationScope[]{new AuthorizationScope("global", "")}))).build());
      }
  

3.使用

相关注解

• @Api：用在类上，说明该类的作用。

• @ApiOperation：注解来给API增加方法说明。

• @ApiImplicitParams : 用在方法上包含一组参数说明。

• @ApiImplicitParam：用来注解来给方法入参增加说明。

• @ApiResponses：用于表示一组响应

• @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

  • code：返回码，例如400

  • message：信息，例如"参数错误"

  • response：抛出异常的类

• @ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）

• @ApiModelProperty：描述一个model的属性

• @ApiIgnore：忽略某个api，可用于单个接口，也可用于整个controller

使用步骤

1. 当然一切的前提是先集成

2. 添加注解

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

     @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 ：echo_yezi@qq.com

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