【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

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

posted @ 2020-08-26 09:18  Echo_Ye  阅读(239)  评论(0)  编辑  收藏  举报