spring boot 配置swagger

前言

• 前端后端分离模式的现在，前端和后端通过api接口进行数据交互。
• 产生一个问题：接口众多，前端和后端无法及时协商
• swagger作用：Api文档自动生成、Api文档自动更新、在线测试Api接口

1.spring boot 引入swagger

<!--Swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2.配置及开启swagger

• 创建如下配置类（项目包的根目录下创建config包，并增加@Configuration注解）

• @Configuration注解注明这是配置类

• @EnableSwagger2注解开启Swagger2

• 注意可以书写多个返回Docker的方法，表示创建多个接口集合。调试界面上可以选择。

• apiInfo为接口集的主页信息展示。构造函数参数如下：

• String title, String description, String version, String termsOfServiceUrl, Contact contact, String license, String licenseUrl, Collection<VendorExtension> vendorExtensions
  

• 基本上.select().apis.paths.build是一套组合进行使用。

• RequestHandlerSelectors类静态方法如下：

• .basePackage("com.zsr.controller") //指定要扫描的包
  .any()//扫面全部
  .none()//不扫描
  .withClassAnnotation(ApiOperation.class):扫描类上的注解(参数是类上注解的class对象)
  .withMethodAnnotation(ApiImplicitParams.class):扫描方法上的注解(参数是方法上的注解的class对象)
  

• PathSelectors类静态方法如下：

• .any()//过滤全部路径
  .none()//不过滤路径
  .ant()//过滤指定路径:按照按照Spring的AntPathMatcher提供的match方法进行匹配
  .regex("/[zsr]/**")//过滤指定路径:按照String的matches方法进行匹配
  

• 可以通过enable(flag)来实现Swagger在开发环境中，在正式环境时不能使用（结合spring boot的配置文件的运行环境）。

  @Configuration
  @EnableSwagger2
  public class SwaggerConfig {
  
      //UserController的接口配置
      @Bean
      public Docket docketLogin(){
          return new Docket(DocumentationType.SWAGGER_2)
                  .apiInfo(apiInfoLogin())
                  .select()
                .enable(flag)//通过flag判断是否开启
                  .apis(RequestHandlerSelectors.basePackage("com.glg.collsheet.controller"))
                  .paths(PathSelectors.any())
                  .build();
      }
      private ApiInfo apiInfoLogin(){
          return new ApiInfo(
                  "LoginController",
                  "登录API文档",
                  "1.0",
                  "xxxxx.com",
                  new Contact("luoyuteng","xxxx.com","wxbl2098@qq.com"),
                  "Apache 2.0",
                  "http://www.apache.org/licenses/LICENSE-2.0",
                  new ArrayList<VendorExtension>()
          );
      }
  }
  

3.常见注解

• 用来对接口进行注解
• 默认情况下只会扫描有这些注解的接口。这种写法更加合理

3.1 @Api注解

• 该注解将一个Controller（Class）标注为一个swagger资源（API）。有如下属性

• tags API分组标签。具有相同标签的API将会被归并在一组内展示。

• value 如果tags没有定义，value将作为Api的tags使用

• description API的详细描述

• @Api(description="用户登录注册")
  public class UserController {}
  

3.2@ApiOperation注解

• 在指定的（路由）路径上，对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。此注解的属性有：

• value 对操作的简单说明

• notes 对操作的详细说明。

• httpMethod HTTP请求的动作名，可选值有："GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"。

• code 默认为200，有效值必须符合标准的HTTP Status Code Definitions。

• @ApiOperation(value="用户注册", notes = "注册会员")
      @RequestMapping(value = "/register", method = RequestMethod.POST)
      @ApiImplicitParams({
              @ApiImplicitParam(name="name",value="用户名",dataType = "String",required=true),
              @ApiImplicitParam(name="age",value="年龄",dataType = "Int",required=true),
              @ApiImplicitParam(name="pwd",value="密码",dataType = "String",required=true)
      })
      public String register(){}
  

3.3@ApiImplicitParams和@ApiImplicitParam注解

• 注解@ApiImplicitParam必须被包含在注解@ApiImplicitParams之内。可以设置以下重要参数属性：
• name 参数名称
• value 参数的简短描述
• required 是否为必传参数
• dataType 参数类型，可以为类名，也可以为基本类型（String，int、boolean等）
• paramType 参数的传入（请求）类型，可选的值有path, query, body, header or form。

4.权限开放

• 权限系统如sa-token等的配置文件中增加如下过滤即可

• .antMatchers("/swagger-ui.html")
  .antMatchers("/swagger-resources/**")
  

参考文章

1."丝袜哥"Swagger来了(整合SpringBoot)

2.Swagger使用和注释介绍

3.Springboot集成Swagger2及常见配置