接口文档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 + '\'' +
                '}';
    }
}