接口文档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 []*/@Beanpublic 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: trueapplication-name: CamundaProjectapplication-version: 1.0application-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 {@Autowiredprivate 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;@Overridepublic String toString() {return "SysForm{" +"id='" + id + '\'' +", type='" + type + '\'' +", title='" + title + '\'' +", body='" + body + '\'' +", pullRefresh='" + pullRefresh + '\'' +", regions='" + regions + '\'' +'}';}
}