建设银行手机银行官方网站下载安装,网站建设产品介绍,注册营业执照申请,html的软件使用原生的swagger作为接口文档#xff0c;功能不够强大#xff0c;并且默认的ui比较简陋#xff0c;不符合大众审美。所以实际开发中推荐使用knife4j对swagger进行增强。knife4j的地址#xff1a;https://gitee.com/xiaoym/knife4j 基本使用
想要使用knife4j非常简单功能不够强大并且默认的ui比较简陋不符合大众审美。所以实际开发中推荐使用knife4j对swagger进行增强。knife4j的地址https://gitee.com/xiaoym/knife4j 基本使用
想要使用knife4j非常简单只要在Springboot项目中引入knife4j的依赖即可
dependencygroupIdcom.github.xiaoymin/groupIdartifactIdknife4j-spring-boot-starter/artifactIdversion2.0.9/version
/dependency注意引入knife4j后会自动引入swagger相关依赖 所以无需再手动引入swagger相关依赖否则会引起版本冲突在使用knife4j的一些增强功能时会报错 我们首先搭建springboot环境创建2个Controller用swagger相关注解来描述
// Controller1
RestController
RequestMapping(controller1)
Api(tags 应用1-Controller1)
public class Controller1 {GetMapping(api1/{id})ApiOperation(api1)public void api1(PathVariable(id) ApiParam(用户id) Long id) {}PostMapping(api2)ApiOperation(api2)public void api2(RequestBody User user) {}
}// Controller2
RestController
RequestMapping(controller2)
Api(tags 应用1-Controller2)
public class Controller2 {GetMapping(api1/{id})ApiOperation(api1)public void api1(PathVariable(id) ApiParam(用户id) Long id) {}PostMapping(api2)ApiOperation(api2)public void api2(RequestBody User user) {}
}// 实体类
Data
ApiModel(用户实体)
public class User {ApiModelProperty(姓名)private String name;ApiModelProperty(年龄)private Integer age;
}然后创建swagger配置类
Configuration
EnableSwagger2WebMvc
public class SwaggerConfig {// 创建Docket存入容器Docket代表一个接口文档Beanpublic Docket webApiConfig(){return new Docket(DocumentationType.SWAGGER_2)// 创建接口文档的具体信息.apiInfo(webApiInfo())// 创建选择器控制哪些接口被加入文档.select()// 指定ApiOperation标注的接口被加入文档.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build();}// 创建接口文档的具体信息会显示在接口文档页面中private ApiInfo webApiInfo(){return new ApiInfoBuilder()// 文档标题.title(标题用户管理系统接口文档)// 文档描述.description(描述本文档描述了用户管理系统的接口定义)// 版本.version(1.0)// 联系人信息.contact(new Contact(baobao, http://baobao.com, baobaoqq.com))// 版权.license(baobao)// 版权地址.licenseUrl(http://www.baobao.com).build();}
}此时启动项目访问ip:端口/doc.html即可看到knife4j的文档界面 增强功能
使用knife4j增强功能的前提是要在yaml配置中开启增强模式
knife4j:enable: true1.添加接口作者 swagger只能给整个文档添加作者不能针对某个接口单独添加作者。knife4j中可以有2种方式给接口添加作者
在Controller类上标注ApiSupport(author 作者名称)这样整个Controller中的所有接口方法将被指定为该作者在Controller接口方法上标注ApiOperationSupport(author 作者名称)这样该接口被指定为该作者
如果ApiSupport和ApiOperationSupport同时指定了作者那么方法级别的ApiOperationSupport优先级更高 2.生产环境关闭文档
目前Springfox-Swagger以及Knife4j提供的资源接口包括如下 swagger中要实现生产环境关闭文档资源需要在配置类中进行编码判断环境比较麻烦。knife4j中只需要在对应环境的配置中添加配置即可
spring:profiles: prod # 指定为生产环境
knife4j:production: true # 开启屏蔽文档资源此时只要以prod环境运行就无法访问到接口文档 注意如果正常非生产环境下不屏蔽文档那么引入了springsecurtiy或者自定义拦截器的时候要排除掉上述表格中的文档资源否则在非屏蔽状态下也将无法访问到文档资源 3.接口排序 接口排序的方式有2种
针对不同Controller排序Controller上标注ApiSupport(order 序号)针对同一个Controller中的不同方法排序同一个Controller不同接口方法上标注ApiOperationSupport(order 序号)
4.导出离线文档
markdown导出当前逻辑分组下所有接口的Markdown格式的文档Html导出当前逻辑分组下所有接口的Html格式的文档Word:导出当前逻辑分组下所有接口的Word格式的文档(自2.0.5版本开始)OpenAPI:导出当前逻辑分组下的原始OpenAPI的规范json结构(自2.0.6版本开始)PDF:未实现 5.过滤请求参数 通常我们在开发接口时,比如一个新增接口和一个修改接口修改接口需要传递主键id、而新增接口则不需要传递此属性但大部分情况,我们只写一个Model类,此时在新增接口时显示主键id会显得很多余。使用自定义增强注解ApiOperationSupport中的ignoreParameters属性可以强制忽略要显示的参数
5.1 忽略表单参数
我们给User实体新增一个id属性 然后新增一个新增用户的接口方法用表单方式接收参数但是忽略掉id。在ApiOperationSupport中的ignoreParameters属性中填写忽略的属性名称即可
PostMapping(addUser)
ApiOperation(添加用户)
ApiOperationSupport(ignoreParameters id) // 忽略掉User中的id属性不显示在文档中
public void addUser(User user) {}注意 ignoreParameters支持以数组形式添加多个忽略参数ignoreParameters支持忽略级联对象的参数比如User实体类中有个Address类型的属性addr那么如果想要忽略Address的属性id那么只需要配置为ignoreParameters addr.id即可如果要忽略的参数过多可以使用includeParameters反向配置 5.2 忽略json参数
如果是以RequestBody形式接收参数那么ignoreParameters中填写参数名.要忽略的属性名即可
PostMapping(addUser2)
ApiOperation(添加用户2)
ApiOperationSupport(ignoreParameters {user.id, user.age})
public void addUser2(RequestBody User user) {}6.AfterScript AfterScript功能是Knife4j自2.0.6版本开始新增的一项特性功能在每个接口进行调试Tab中,开发者可以根据Knife4j提供的全局变量,在接口调用之前编写一段JavaScript脚本,当接口调用成功后,Knife4j会执行该脚本
主要应用场景针对JWT类型的接口调用登录接口后每个接口请求时带上Token参数此时可以通过该脚本动态赋值全局token参数省去复制粘贴的麻烦
Knife4j目前主要提供ke(Knife4j Environment)对象来获取或者操作全局对象,主要包含的对象
global:全局操作,可以获取或者设置目前的全局参数 setHeader(name,value):设置当前逻辑分组下的全局参数Header请求头setAllHeader(name,value):设置所有逻辑分组下的全局参数Header请求头setParameter(name,value):设置当前逻辑分组下主要是针对query类型参数进行设置全局设置。setAllParameter(name,value):设置所有逻辑分组下的全局参数主要是query类型response:当前请求接口响应内容 headers:服务端响应Header对象,注意,此处所有的header的名称全部进行小写转换data:服务端响应数据(json/xml/text等等)
我们新增一个登录接口返回token参数
PostMapping(login)
ApiOperation(登录)
public MapString, Object login() {MapString, Object result new HashMap(2);result.put(success, true);result.put(token, 1364564646);return result;
}然后在knife4j文档中针对这个登录接口编写AfterScript取出返回的token设置到每一个请求的请求头中
var successke.response.data.success;
if(successtrue){// 获取tokenvar tokenke.response.data.token;// 设置当前逻辑分组下的全局Headerke.global.setHeader(Authorization, Bearer token);
}这样的效果是请求login接口成功返回token后后续调试其他所有接口时会自动给请求头中添加token参数无需手动添加 7.全局参数
Knife4j提供基于UI临时设置全局参数功能,例如后台全局token参数等.提供该功能主要是方便开发者进行调试
目前全局参数功能主要提供两种参数类型query(表单)、header(请求头)
如果后端Swagger有配置全局参数该功能可以无视 微服务文档聚合
在微服务架构下如果给每个微服务都配置文档那么每个微服务的接口文档都有自己独立的访问地址这样要一个个打开每个微服务的文档非常麻烦。一般我们会采用聚合的办法将所有微服务的接口整合到一个文档中
传统的整合方法需要在gateway中进行大量配置十分繁琐。自2.0.8版本开始Knife4j 提供了knife4j-aggregation-spring-boot-starter组件该组件是一个基于Spring Boot系统的starter他提供了以下几种能力
最轻量级、最简单、最方便的聚合OpenApi规范的中间件 让所有的基于Spring Boot的Web体系拥有了轻松聚合OpenApi的能力 提供4种模式供开发者选择
基于本地静态JSON文件的方式聚合OpenAPI基于云端HTTP接口的方式聚合基于Eureka注册中心的方式聚合基于Nacos注册中心的方式聚合
基于该starter发布了Docker镜像跨平台与语言让开发者基于此Docker镜像轻松进行聚合OpenAPI规范 完美兼容所有Spring Boot版本没有兼容性问题 开发者可以彻底放弃基于Zuul、Spring Cloud Gateway等复杂的聚合方式 兼容OpenAPI2规范以及OpenAPI3规范 目前Knife4jAggregation主要提供了四种方式进行OpenAPI文档的聚合主要包括
基于OpenAPI的静态JSON文件方式Disk模式基于HTTP接口的方式获取OpenAPICloud模式基于Eureka注册中心获取OpenAPIEureka模式基于Nacos注册中心获取OpenAPINacos模式 Disk、Cloud、Eureka、Nacos这四种模式只能使用其中1种不能混合一起使用(即只能配置这4中模式中的一种属性然后将其enable属性设置为true,其他三种的enable则必须设置为false) 利用knife4j进行文档聚合的步骤非常简单
1、创建一个SpringBoot项目用于聚合文档引入下列依赖 dependencygroupIdcom.github.xiaoymin/groupIdartifactIdknife4j-aggregation-spring-boot-starter/artifactIdversion2.0.9/version
/dependency配置需要聚合的文档的地址 访问该聚合文档的地址即可访问到被聚合的所有接口文档
1.Cloud模式
cloud模式原理是在聚合文档工程配置每个微服务的http接口资源地址这样聚合文档工程启动的时候可以访问到每个微服务的http接口文档资源地址从而聚合每个微服务的接口文档 这种方式可以用在没有注册中心每个SpringBoot微服务单独启动的场景由于聚合文档工程需要能访问到每个微服务的http接口文档资源地址才能做聚合所以在聚合文档工程启动之前要先启动需要被聚合的每个微服务并且每个微服务自己要做好swagger文档的相关配置 为了测试聚合文档我们首先复制出一个SpringBoot工程knife4j-app2作为第2个微服务其主要配置与knife4j-app1一样只是部分地方作了名称修改。然后再创建一个聚合文档工程knife4j-agg-doc 在聚合文档工程knife4j-agg-doc中引入依赖 dependencygroupIdcom.github.xiaoymin/groupIdartifactIdknife4j-aggregation-spring-boot-starter/artifactIdversion2.0.9/version
/dependencycloud模式中yaml的配置示例如下
knife4j:enableAggregation: truecloud:enable: trueroutes:- name: 用户体系uri: 192.168.0.152:8999location: /v2/api-docs?group2.X版本swaggerVersion: 2.0servicePath: /abbb/fferouteAuth:enable: trueusername: test3password: 66666routeAuth:enable: trueusername: testpassword: 12313knife4j.cloud.enable:将该属性设置为true则代表启用Cloud模式 knife4j.cloud.routeAuth:该属性是一个公共Basic验证属性(可选)如果开发者提供的OpenAPI规范的HTTP接口需要以Basic验证进行鉴权访问那么可以配置该属性如果配置该属性则该模式下所有配置的Routes节点接口都会以Basic验证信息访问接口knife4j.cloud.routeAuth.enable:是否启用Basic验证 knife4j.cloud.routeAuth.usernae:Basic用户名 knife4j.cloud.routeAuth.password:Basic密码 knife4j.cloud.routes:需要聚合的服务集合(必选)可以配置多个 knife4j.cloud.routes.name:服务名称(显示名称最终在Ui的左上角下拉框进行显示) knife4j.cloud.routes.uri:该服务的接口URI资源如果是HTTPS则需要完整配置 knife4j.cloud.routes.location::具体资源接口地址最终Knife4j是通过urilocation的组合路径进行访问 knife4j.cloud.routes.swaggerVersion:版本号默认是2.0可选配置 knife4j.cloud.routes.servicePath:该属性是最终在Ui中展示的接口前缀属性提供该属性的目的也是因为通常开发者在以Gateway等方式聚合时需要一个前缀路径来进行转发而最终这个前缀路径会在每个接口中进行追加 knife4j.cloud.routes.routeAuth:如果该Route节点的接口开启了Basic并且和公共配置的Basic不一样需要单独配置 knife4j.cloud.routes.routeAuth.enable:是否启用Basic验证 knife4j.cloud.routes.routeAuth.usernae:Basic用户名 knife4j.cloud.routes.routeAuth.password:Basic密码 我们在knife4j-agg-doc的yaml中做如下配置
server:port: 8010knife4j:enableAggregation: true # 开启聚合cloud:enable: true # 开启cloud模式routes: - name: 应用1 # 微服务在聚合文档中的名称uri: localhost:8000 # 微服务的http地址location: /v2/api-docs # 微服务文档资源路径servicePath: /api/app1 # 给每个接口添加路径前缀作用是拼接出经过nginx和gateway处理前的实际接口url- name: 应用2uri: localhost:8001location: /v2/api-docs?groupdefaultservicePath: /api/app2然后先启动knife4j-app1与knife4j-app2再启动knife4j-agg-doc访问knife4j-agg-doc的地址http://localhost:8010/doc.html即可看到聚合后的文档 可以发现不同的微服务是以不同分组的形式出现在聚合文档中所以实际上配置文档聚合是聚合某个微服务中的某个分组 在配置routes.location的时候可以指定分组参数group默认不指定代表groupdefault。这也意味着我们不止可以细化到每个微服务还可以细化到一个微服务的不同分组。如果每个微服务的swagger文档中配置了多个分组可以聚合每一个分组这样聚合文档中可以区分选择某一个微服务下具体分组的文档 实际开发中一般情况下不建议在一个微服务中再进行分组否则不好管理。每个微服务都用默认分组直接以微服务为单位聚合文档即可清晰区分开每个微服务的接口 2.Nacos模式
Nacos模式原理是在聚合文档工程配置每个微服务的Nacos注册中心地址和服务名称这样聚合文档工程启动的时候可以从Nacos访问到每个微服务的http接口文档资源地址从而聚合每个微服务的接口文档 这种方式适合以Nacos作为微服务注册中心的场景由于聚合文档工程需要能访问到Nacos获取每个微服务的信息才能做聚合所以在聚合文档工程启动之前要先启动Nacos和需要被聚合的每个微服务并且每个微服务要成功注册到Nacos中每个微服务自己要做好swagger文档的相关配置 为了测试Nacos模式首先在每个微服务中引入nacos相关依赖和配置并启动Nacos和微服务将它们注册到Nacos中 Nacos模式的可选配置如下
knife4j:enableAggregation: truenacos:enable: trueserviceUrl: http://192.168.0.112:8804/nacos/routeAuth:enable: trueusername: testpassword: 12313routes:- name: 订单服务serviceName: service-ordergroupName: testnamespaceId: testclusters: testlocation: /v2/api-docs?groupdefaultswaggerVersion: 2.0servicePath: /orderrouteAuth:enable: trueusername: testpassword: 12313knife4j.nacos.enable:将该属性设置为true则代表启用nacos模式 knife4j.nacos.serviceUrl:nacos注册中心的地址 knife4j.nacos.routeAuth:该属性是一个公共Basic验证属性(可选)如果开发者提供的OpenAPI规范的服务需要以Basic验证进行鉴权访问那么可以配置该属性如果配置该属性则该模式下所有配置的Routes节点接口都会以Basic验证信息访问接口 knife4j.nacos.routeAuth.enable:是否启用Basic验证 knife4j.nacos.routeAuth.usernae:Basic用户名 knife4j.nacos.routeAuth.password:Basic密码 knife4j.nacos.routes:需要聚合的服务集合(必选)可以配置多个 knife4j.nacos.routes.name:服务名称(显示名称最终在Ui的左上角下拉框进行显示)如果该属性不配置最终Ui会显示serviceName knife4j.nacos.routes.serviceName:nacos注册中心的服务名称 knife4j.nacos.routes.groupName:Nacos分组名称,非必须,开发者根据自己的实际情况进行配置 knife4j.nacos.routes.namespaceId:命名空间id,非必须,开发者根据自己的实际情况进行配置 knife4j.nacos.routes.clusters:集群名称,多个集群用逗号分隔,非必须,开发者根据自己的实际情况进行配置 knife4j.nacos.routes.uri:该服务的接口URI资源如果是HTTPS则需要完整配置 knife4j.nacos.routes.location::具体资源接口地址最终Knife4j是通过注册服务urilocation的组合路径进行访问 knife4j.nacos.routes.swaggerVersion:版本号默认是2.0可选配置 knife4j.nacos.routes.servicePath:该属性是最终在Ui中展示的接口前缀属性提供该属性的目的也是因为通常开发者在以Gateway等方式聚合时需要一个前缀路径来进行转发而最终这个前缀路径会在每个接口中进行追加 knife4j.nacos.routes.routeAuth:如果该Route节点的接口开启了Basic并且和公共配置的Basic不一样需要单独配置 knife4j.nacos.routes.routeAuth.enable:是否启用Basic验证 knife4j.nacos.routes.routeAuth.usernae:Basic用户名 knife4j.nacos.routes.routeAuth.password:Basic密码 我们在聚合文档工程knife4j-agg-doc的yaml中做如下配置
server:port: 8010knife4j:enableAggregation: truenacos:enable: true # 开启Nacos模式serviceUrl: http://localhost:8848/nacos # Nacos注册中心地址routes:- name: 应用1 # 微服务在聚合文档中的名称serviceName: APP1 # 微服务在Nacos注册中心的名称location: /v2/api-docs # 微服务文档资源路径servicePath: /api/app1 # 给每个接口添加路径前缀作用是拼接出经过nginx和gateway处理前的实际接口url- name: 应用2serviceName: APP2location: /v2/api-docsservicePath: /api/app2启动聚合文档工程访问http://localhost:8010/doc.html查看聚合文档
