腾讯网站谁做的,校园网站建设培训班,合肥瑶海区邮编,鞍山网站建设鞍山Spring-接口文档swagger2
1、swagger/knife4j 接口文档配置
knife4j是swagger的增强版本#xff0c;更加的小巧、轻量#xff0c;功能也是更加的完善#xff0c;UI也更加的清晰#xff1b;可以从swagger到knife4j无缝切换。
1.1 引入相关依赖 !--接口文档的开发:…Spring-接口文档swagger2
1、swagger/knife4j 接口文档配置
knife4j是swagger的增强版本更加的小巧、轻量功能也是更加的完善UI也更加的清晰可以从swagger到knife4j无缝切换。
1.1 引入相关依赖 !--接口文档的开发: knife4j是swagger的增强版本更加的小巧、轻量功能也是更加的完善UI也更加的清晰可以从swagger到knife4j无缝切换。--
dependencygroupIdio.springfox/groupIdartifactIdspringfox-boot-starter/artifactIdversion3.0.0/version
/dependency
dependencygroupIdcom.github.xiaoymin/groupIdartifactIdknife4j-spring-boot-starter/artifactIdversion3.0.3/version
/dependencyswagger接口文档访问地址: 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 1299637404qq.com
swagger.version 1.01.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: true2、swagger常用注解
2.1 Api 注解
用在请求的类上表示对类的说明常用属性介绍 tags“说明该类的作用可以在UI界面上看到的注解” value“该参数没什么意义在UI界面上也看到所以不需要配置” Api的其它属性配置 属性名称作用valueurl的路径值tags如果设置这个值、value的值会被覆盖description对api资源的描述basePath基本路径position如果配置多个Api 想改变显示的顺序位置produces如, “application/json, application/xml”consumes如, “application/json, application/xml”protocols协议类型如: http, https, ws, wssauthorizations高级特性认证时配置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 -- 请求参数的获取RequestHeaderquery -- 请求参数的获取RequestParampath用于restful接口– 请求参数的获取PathVariablebody不常用form不常用 ApiOperationSupport( order1/2/3 ) 同一类中的接口排列顺序 2.3 接口响应状态的描述 ApiResponses 方法返回值的说明 。 ApiResponses响应状态的说明。是个数组可包含多个 ApiResponse ApiResponse用于指定单个参数的说明。 属性值 code数字例如400message信息例如请求参数没填好 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)ResponseBodyApiImplicitParams({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 表单定义体:表单中的主体数据类型(ListMapObject,Object),required true)private ListMapObject,Object body;/** 表单pullRefresh */ApiModelProperty(value pullRefresh(MapObject,Object),required true)private MapObject,Object pullRefresh;/** 表单regions */ApiModelProperty(value regions(ListObject),required true)private ListObject regions;Overridepublic 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
