Knife4j 2.0.8 发布,轻量级微服务聚合文档中间件诞生

西域战神 2020-11-23 11:06:16 ⋅ 106 阅读

Knife4j前身是swagger-bootstrap-ui,是一个为Swagger接口文档赋能的工具

文档https://xiaoym.gitee.io/knife4j/

效果(旧版)http://swagger-bootstrap-ui.xiaominfo.com/doc.html

效果(2.X版)http://knife4j.xiaominfo.com/doc.html

Giteehttps://gitee.com/xiaoym/knife4j

GitHubhttps://github.com/xiaoymin/swagger-bootstrap-ui

示例https://gitee.com/xiaoym/swagger-bootstrap-ui-demo

特性 & 优化

1、构建响应curl时,去除Knife4j自定义添加的部分Header头

2、增加自定义主页的增强配置,开发者可以提供一个Markdown文档,用来自定义Home主页显示的内容Gitee #I24ZXI

knife4j:
    enable: true
    setting:
        # 是否自定义显示Home主页,默认为false
        enableHomeCustom: true
        # 自定义主页Home的markdown文档路径,只能设置1个,如果设置为目录,则默认取第一个
        homeCustomLocation: classpath:markdown/home.md

3、OpenAPI开放接口可以通过增强配置是否显示Gitee #I25273

knife4j:
    enable: true
    setting:
        # 是否显示文档中的Open标签栏,默认为true
        enableOpenApi: false

4、搜索框可以通过增强配置是否显示Gitee #I24ZYY

knife4j:
    enable: true
    setting:
        # 是否显示文档中的搜索框,默认为true,即显示
        enableSearch: false

5、文档最下边的footerkey通过增强配置是否显示,并且可以自定义显示内容Gitee #I24ZYD

knife4j:
    enable: true
    setting:
        # 是否不显示Knife4j默认的footer,默认为true(显示)
        enableFooter: false
        # 是否自定义Footer,默认为false(非自定义)
        enableFooterCustom: true
        # 自定义Footer内容,支持Markdown语法
        footerCustomContent: 中国XXX科技股份有限公司版权所有

6、废弃springfox中的控制参数接口/swagger-resources/configuration/ui,针对是否开启Debug调试,通过Knife4j提供的个性化增强配置进行控制

knife4j:
    enable: true
    setting:
        # 是否显示调试Tab框架,默认为true(显示)
        enableDebug: false

7、解决微服务架构下,丢失basePath的问题Gitee #I23NWMGitee #I23N6LGitee #I25ZTCGitHub #286

8、自定义文档以及自定义Home主页的Markdown支持Html语法Gitee #I24ZZA

9、去除文档右上角?号的文档显示Gitee #I24ZYL

10、增强配置增加开启动态请求参数配置的配置Gitee #I24EBO

knife4j:
    enable: true
    setting:
        # 开启动态请求参数调试,默认为false(不开启)
        enableDynamicParameter: true

11、如果当前服务只有一个分组的情况下,开发者可以通过配置enableGroup项来控制界面的分组显示Gitee #I25MQG,配置如下:

knife4j:
    enable: true
    setting:
        # Ui界面不显示分组元素
        enableGroup: false

最终效果图如下:

12、基础类型的请求参数与响应参数示例显示优化Gitee #I24YKT

13、@ApiOperationSupport@DynamicParameters注解不能同时使用的问题Gitee #I24JWV

14、解决V3版本中starter存在冲突的问题Gitee #I2420J

15、优化markdown渲染的组件方式。

16、离线文档导出移除导出PDF项,导出pdf功能不管是基于markdown或者是word都能轻松实现,因此Knife4j废弃此功能

17、OpenAPI3结构中支持表单类型中scheme解析显示为jsonGitee #I24PCZ

18、针对Authorize标志的接口,添加锁的icon在接口中进行体现Gitee #I23W0S 

19、增强配置本地缓存更新策略

20、针对禁用文档管理菜单项后,同步禁用右上角个性化菜单的显示。Gitee #I262VN

21、请求OpenAPI规范实例接口默认发送一个language的header,如果服务端做了i18n的配置可以根据此header动态返回不同的语言释义。

21、解决根据路径设置界面i18n显示时,和服务端增强配置冲突的问题,如果开发者通过url路径来设置界面的i18n显示,则默认以路径中的为准,否则,取后端增强配置的language

22、菜单收缩时显示存在异常的问题Gitee #I2646F

23、OpenAPI3规范适配支持JSR303支持GitHub #283

24、请求参数的数据类型为空的情况下优化,显示默认值string

使用方法

Java开发使用Knife4j目前有一些不同的版本变化,主要如下:

1、如果开发者继续使用OpenAPI2的规范结构,底层框架依赖springfox2.10.5版本,那么可以考虑Knife4j的2.x版本

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <!--在引用时请在maven中央仓库搜索2.X最新版本号-->
    <version>2.0.8</version>
</dependency>

2、如果开发者使用OpenAPI3的结构,底层框架依赖springfox3.0.0,可以考虑Knife4j的3.x版本

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <!--在引用时请在maven中央仓库搜索3.X最新版本号-->
    <version>3.0.2</version>
</dependency>

3、如果开发者底层框架使用的是springdoc-openapi框架,则需要使用Knife4j提供的对应版本,需要注意的是该版本没有Knife4j提供的增强功能,是一个纯Ui。

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-springdoc-ui</artifactId>
    <!--在引用时请在maven中央仓库搜索3.X最新版本号-->
    <version>3.0.2</version>
</dependency>

Knife4jAggregation微服务聚合中间件

2.0.8版本开始,Knife4j提供了轻量级的聚合微服务OpenAPI文档的中间件,可以在任意Spring Boot服务中聚合文档,最简单、最轻量级、最方便的聚合组件

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-aggregation-spring-boot-starter</artifactId>
    <!--在引用时请在maven中央仓库搜索Knife4jAggregation最新版本号-->
  <version>2.0.8</version>
</dependency>

该组件提供了4种不同的模式以满足不同语言、不同模式的方式进行OpenAPI文档的聚合

四种不同的方式:

更详细的介绍以及实战使用方法请参考文档

特点

  • 基于Vue+Ant Design构建的文档,更强大、清晰的接口文档说明能力以及接口调试能力

  • 左右布局,基于Tabs组件的多文档查阅风格

  • 支持在线导出Html、Markdown、Word、PDF等多种格式的离线文档

  • 接口排序,支持分组及接口的排序功能

  • 支持接口全局在线搜索功能

  • 提供Swagger资源保护策略,保护文档安全

  • 接口调试支持无限参数,开发者调试非常灵活,动态增加、删除参数

  • 全局缓存调试信息,页面刷新后依然存在,方便开发者调试

  • 以更人性化的table树组件展示Swagger Models功能

  • 文档以多tab方式可显示多个接口文档

  • 请求参数栏请求类型、是否必填着颜色区分

  • 主页中粗略统计接口不同类型数量

  • 支持自定义全局参数功能,主页包括header及query两种类型

  • JSR-303 annotations 注解的支持

  • 更多个性化设置功能

界面

接口文档显示界面如下:

接口调试界面如下:

Swagger Models功能

支持导出离线Markdown、Html功能,markdown的表格较原先版本通过缩减显示为树形结构,点击预览导出离线Html效果,效果图如下:

通过第三方Markdown软件导出的PDF效果如下图:

同时提供了导出离线Html功能,Html功能界面风格和在线几乎没有区别,美观、大方、简洁,点击在线预览效果

界面效果如下图:


全部评论: 0

    我有话说:

    Swagger接口文档工具:Knife4j 2.0.7 发布,细节优化

    Knife4j前身是swagger-bootstrap-ui,是一个为Swagger接口文档赋能的工具 文档:https://doc.xiaominfo.com 效果(旧版):http

    【开源资讯】JWCloud 专业版 v1.0.0 发布,基于 SpringCloud 研发的服务框架

    简介 JavaWeb_Cloud 服务平台是一款基于 SpringCloud 框架研发的分布式微服务框架,主要使用技术栈包括: SpringCloud、Vue、ElementUI

    Micronaut 2.4.0 发布,基于 JVM 的服务应用框架

    ,Micronaut 2.4.0 正式发布,本次更...

    Apache APISIX 2.4 发布,云原生的服务 API 网关

    Apache APISIX 2.4 已经发布。Apache APISIX 是一个云原生服务 API 网关,它提供了高性能、安全、开源和可扩展的平台,基于 Nginx 和 etcd,支持动态路由和插

    Martian-cloud 4.0,跟注册中心拜拜了,基于传染机制的分布式组件诞生

    这次真的要跟注册中心讲拜拜了,服务不再需要占用一套注册中心集群了,大大节约了运维成本 更新点如下 丢弃了一开始的【生产者->注册中心->消费者】模型 采用传染机制,实现服务发现

    Micronaut 2.4.2 发布,基于 JVM 的服务应用框架

    ,Micronaut 2.4.2 正式发布,本次更...

    Helidon 2.1.0 发布,Oracle 服务框架

    Helidon 2.1.0 现已发布,这是一个次要发行版,包含了一些错误修复和增强功能。Helidon 是 Oracle 开源的一个用于编写服务的 Java 框架,这些微服务运行在由 Netty

    Apache SkyWalking 8.2.0 发布:新增浏览器端监控和指标分析语言、使用标签查询

    Apache SkyWalking 8.2.0发布,SkyWalking 是观察性分析平台和应用性能管理系统 (APM),提供分布式追踪、服务网格遥测分析、度量聚合和可视化一体化解决方案,支持

    SpringBlade v2.8.0 已经发布,SaaS 服务开发平台

    SpringBlade服务开发平台 采用前后端分离的模式,前端开源两个框架:Sword (基于 React、Ant Design)、Saber (基于 Vue、Element

    极速后台框架 FastAdmin v1.2.0.20210125 新增插 API 文档生成

    FastAdmin 更新日志 v1.2.0.20210125_beta 新增自定义插API文档生成 新增登录和鉴权状态显示 新增自定义测试提交参数 优化安装脚本 优化cookie加密 修复系统

    你的老板逼你上服务了吗?

    “ 这些年软件的设计规模越来越庞大,业务需求也越来越复杂,针对系统的性能、高吞吐率、高稳定性、高扩展等特性提出了更高的要求。   图片来自 Pexels可以说业务需求是软件架构能力的第一推动力,由于这些因素导致了软件架构思想和相关技...

    OpenSSH 8.4 发布

    OpenSSH 8.4发布,OpenSSH 是 100% 完整的 SSH 协议 2.0 版本的实现,并且包括 sftp 客户端和服务器支持,它用于远程登录的主要连接工具。OpenSSH 对所有

    京东技术:如何实现百万TPS?详解JMQ4的存储设计

    JMQ是京东中间团队自研的消息中间诞生于2014年,服务京东近万个应用,2018年11.11大促期间的峰值流量超过5000亿条消息

    阿里巴巴中间-Nacos 发布 v0.8.0 Pre-GA版本,安全稳定上生产

    服务注册和服务配置开源项目 Nacos 本周发布了 v0.8.0 Pre-GA 版本,作为开源项目生命周期中的里程碑版本之一

    「转载」服务分布式架构中,如何实现日志链路跟踪?

    背景 开发排查系统问题用得最多的手段就是查看系统日志,在分布式环境中一般使用ELK来统一收集日志,但是在并发大时使用日志定位问题还是比较麻烦,我们来看下面的图     上图一个用户请求一个url,整个链路如图,每个处理层...

    「开源资讯」BookChat v2.4 发布,通用书籍阅读信小程序

    BookChat - 面向程序员的开源书籍和文档阅读学习小程序

    Istio 1.8.3 发布,大型服务系统管理工具

    Istio 1.8.3 已发布,Istio 是一个由谷歌、IBM 与 Lyft 共同开发的开源项目,旨在提供一种统一化的服务连接、安全保障、管理与监控方式。具体来说,Istio 是一个开源服务网格

    PowerJob v3.3.2 已经发布,分布式任务调度中间

    PowerJob v3.3.2 已经发布,PowerJob 是全新一代分布式调度与计算框架,能让您轻松完成作业的调度与繁杂任务的分布式计算。 此版本更新内容包括: Features 支持控制台查看