接口文档swagger2的使用

Spring-接口文档swagger2

1、swagger/knife4j 接口文档配置

​ knife4j是swagger的增强版本，更加的小巧、轻量，功能也是更加的完善，UI也更加的清晰；可以从swagger到knife4j无缝切换。

1.1 引入相关依赖

 <!--接口文档的开发: knife4j是swagger的增强版本，更加的小巧、轻量，功能也是更加的完善，UI也更加的清晰；可以从swagger到knife4j无缝切换。-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

swagger接口文档访问地址:

http://192.168.0.145:9991/swagger-ui/index.html

knife4j接口文档的访问地址：

http://192.168.0.145:9991/doc.html

1.2 创建Swagger配置类

​ 我这里的接口文档信息，是通过application.properties 中配置注入的，这样方便修改相关信息，而不同改变源码。

package cn.zhidasifang.common.config;

import com.sun.org.apache.xpath.internal.operations.Bool;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.SpringApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author: AD_Liu
 * @Description: 接口文档Swagger配置类
 * @ClassName: SwaggerConfig
 */
@Component
@EnableSwagger2
public class SwaggerConfig {
    @Value("${swagger.enable}")
    private Boolean swaggerEnable;
    @Value("${swagger.title}")
    private String title;
    @Value("${swagger.description}")
    private String description;
    @Value("${swagger.contact.name}")
    private String name;
    @Value("${swagger.contact.url}")
    private String url;
    @Value("${swagger.contact.email}")
    private String email;
    @Value("${swagger.version}")
    private String version;

    /**
     * @return springfox.documentation.service.ApiInfo
     * @Description:获取封装好的接口文档信息
     * @Param []
     */
    public ApiInfo getApiInfo() {
        return new ApiInfoBuilder()
                //设置标题
                .title(title)
                //描述
                .description(description)
                //作者信息
                .contact(new Contact(name, url, email))
                .termsOfServiceUrl(url)
                //版本
                .version(version)
                .build();
    }

    /**
     * @return springfox.documentation.spring.web.plugins.Docket
     * @Description:定义接口文档的基本信息
     * @Param []
     */
    @Bean
    public Docket configUi() {
        return new Docket(DocumentationType.SWAGGER_2)
                //统一前缀的配置？
                //.pathMapping(url)
                //定义是否开启 swagger。false关闭
                .enable(swaggerEnable)
                //创建api的基本信息
                .apiInfo(getApiInfo())
                //选择那些接口作为swagger的doc发布
                .select()
                //控制那些接口暴露给swagger
                //.apis(RequestHandlerSelectors.any()) //所有暴露
                //RequestHandlerSelectors.basePackage("com.demo.security.*") 指定包定位
                //RequestHandlerSelectorswithMethodAnnotation(ApiOperation.class) 标记又 @ApiOperation注解 的接口暴露
                //.apis(RequestHandlerSelectors.basePackage("cn.zhidasifang.camundaproject.SalaryProcess.controller"))
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //.paths(PathSelectors.regex("/error").negate())
                .paths(PathSelectors.any())
                .build();
    }
}

• application.properties 文件中的数据

#接口文档相关配置信息
swagger.enable = true
swagger.title = 流程控制相关_接口文档
swagger.description = 流程中相关接口文档，接口分类：流程模快定义、流程任务处理、表单模快等
swagger.contact.name = Liu
swagger.contact.url = 192.168.0.145:9991
swagger.contact.email = 1299637404@qq.com
swagger.version = 1.0

1.3 application.yml 配置文件中的相关配置信息

​ 高版本的SpringBoot 在整合 Swagger 时，还需要在yml 文件中配置增加路径配置，这里需要在spring.mvc.pathmatch.matching-strategy:项中配置 匹配路径 ant_path_matcher。

​ 否则就会在项目启动时报错！

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher #swagger配置
      
#Swagger配置      
swagger:
  enable: true
  application-name: CamundaProject
  application-version: 1.0
  application-description: client
knife4j:
  enable: true

2、swagger常用注解

2.1 @Api 注解

​ 用在请求的类上，表示对类的说明：常用属性介绍：

• tags=“说明该类的作用，可以在UI界面上看到的注解”

• value=“该参数没什么意义，在UI界面上也看到，所以不需要配置”

  @Api的其它属性配置

  属性名称	作用
  value	url的路径值
  tags	如果设置这个值、value的值会被覆盖
  description	对api资源的描述
  basePath	基本路径
  position	如果配置多个Api 想改变显示的顺序位置
  produces	如, “application/json, application/xml”
  consumes	如, “application/json, application/xml”
  protocols	协议类型，如: http, https, ws, wss
  authorizations	高级特性认证时配置
  hidden	配置为true ，将在文档中隐藏

ApiSupport( order =1/2/3 ) 文档中接口类排序顺序注解

2.2 方法/方法参数描述注解

​ 主要涉及到三个注解分别是：

2.2.1 @ApiOperation注解

@ApiOperation：用在请求的方法上，说明方法的用途、作用

属性 value=“说明方法的用途、作用”

属性 notes=“方法的备注说明”

2.2.2 @ApiImplicitParams注解

@ApiImplicitParams：方法参数的说明

@ApiImplicitParams注解需要包含一个或者多个 @ApiImplicitParam注解。格式如下

@ApiImplicitParams({
        @ApiImplicitParam(name = "sysForm",value ="ApiImplicitParam表单定义实体类参数1111")
})

2.2.3 @ApiImplicitParam注解

@ApiImplicitParam：用于指定单个参数的说明

@ApiImplicitParam注解，可以单独使用在方法上，能说明单个参数的相关信息。也可包含在@ApiImplicitParams注解中使用。对应的属性有如下所示：

属性名称	作用
name	参数名
value	参数的汉字说明、解释
required	参数是否必须传
paramType	参数放在哪个地方
dataType	参数类型，默认String，其它值dataType=“Integer”
defaultValue	参数的默认值

其中 paramType 属性对应用下面几种类型：

• header --> 请求参数的获取：@RequestHeader
• query --> 请求参数的获取：@RequestParam
• path（用于restful接口）–> 请求参数的获取：@PathVariable
• body（不常用）
• form（不常用）

@ApiOperationSupport( order=1/2/3 ) 同一类中的接口排列顺序

2.3 接口响应状态的描述

• @ApiResponses ： 方法返回值的说明 。

  @ApiResponses：响应状态的说明。是个数组，可包含多个 @ApiResponse

• @ApiResponse：用于指定单个参数的说明。

  属性值：

  • code：数字，例如400
  • message：信息，例如"请求参数没填好"
  • ​ response：抛出异常的类

2.4 实体类对象描述注解

主要包含两个注解分别是

• @ApiModel :经常用于请求的入参对象 和 响应返回值对象的描述，在接口方法上使用

  属性描述：

  • 属性value ： 实体类名称
  • 属性notes ：实体类描述信息

• @ApiModelProperty ：用于每个属性上面，说明属生的含义。

3、示例展示

• Controller层接口文档注解演示

  /**
   * @author AD
   * @Description: xxxx
   * @ClassName: FormInfoResource
   *
   */
  @Controller
  @RequestMapping("/form/formInfo")
  @Api(tags = "自定义表单管理接口")
  public class FormController {
      @Autowired
      private IFormInfoService formInfoService;
  
      @PostMapping("/test")
      @ResponseBody
      @ApiImplicitParams({
              @ApiImplicitParam(name = "sysForm",value ="ApiImplicitParam表单定义实体类参数1111")
      })
      public String testForm(@RequestBody SysForm sysForm){
          System.out.println("sysForm = " + sysForm);
          formInfoService.saverFormInfo(sysForm);
          return "测试多项目模快成！";
      }
  }
  

  ​

• 实体类接口文档注解演示

  package cn.zhidasifang.formmanagement.model;
  
  import io.swagger.annotations.ApiModel;
  import io.swagger.annotations.ApiModelProperty;
  import lombok.AllArgsConstructor;
  import lombok.Data;
  import lombok.NoArgsConstructor;
  import lombok.ToString;
  import lombok.experimental.Accessors;
  import springfox.documentation.spring.web.json.Json;
  
  import java.io.Serializable;
  import java.util.List;
  import java.util.Map;
  
  /**
   * 流程表单对象 sys_task_form
   * @author AD
   * @author Tony
   */
  
  @Data
  @NoArgsConstructor
  @AllArgsConstructor
  @Accessors(chain = true) /**支持链式编程*/
  @ApiModel(value = "自定义表单实体类",description = "自定义表单对应的实体类，实体类出现在自定义表单创建时/前端解析自定义表单类型数据时。")
  public class SysForm implements Serializable {
  
      /** 表单主键 */
      @ApiModelProperty(value = "定义表单主键(String)",required = true)
      private String id;
  
      /** 表单类型 */
      @ApiModelProperty(name = "",value ="定义表单的格式类型(String)",required = true)
      private String type;
  
      /** 表单名称 */
      @ApiModelProperty(value = "表单定义时所代表的单据类型(String)",required = true)
      private String title;
  
      /** 表单内容:json格式的数据 */
      @ApiModelProperty(value = "表单定义体:表单中的主体数据类型(List<Map<Object,Object>>)",required = true)
      private List<Map<Object,Object>> body;
  
      /** 表单pullRefresh */
      @ApiModelProperty(value ="pullRefresh(Map<Object,Object>)",required = true)
      private Map<Object,Object> pullRefresh;
  
      /** 表单regions */
      @ApiModelProperty(value = "regions(List<Object>)",required = true)
      private List<Object> regions;
  
      @Override
      public String toString() {
          return "SysForm{" +
                  "id='" + id + '\'' +
                  ", type='" + type + '\'' +
                  ", title='" + title + '\'' +
                  ", body='" + body + '\'' +
                  ", pullRefresh='" + pullRefresh + '\'' +
                  ", regions='" + regions + '\'' +
                  '}';
      }
  }
  

• 访问画面展示

  Swagger接口文档访问展示：http://192.168.0.145:9991/swagger-ui/index.html

  

​ knife4j接口文档访问展示：http://192.168.0.145:9991/doc.html