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

技术小白 2020-11-02 15:39:57 ⋅ 338 阅读

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

文档https://doc.xiaominfo.com

效果(旧版)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、服务端创建Docket对象时配置globalOperationParameters参数时,header类型不选中或丢失的问题

2、如果服务端写会的json参数中包含base64的图片格式,在响应栏增加图片标签直接显示

3、springfox升级到2.10.5版本后,针对basePath会在解析时自动追加到path节点,因为以前的版本没有追加,所以会导致重复添加basePath的问题。Gitee #I230K8Gitee #I23G5V

4、导出出md离线文档请求参数部分字段的设置和文档中同步Gitee #I22UFA

5、字段参数说明支持html标签样式。Gitee #I22RZ2

示例代码:

@ApiModelProperty(value = "奖金名称,记住:<br /><span style=\"color:red\">我很重要</span>",example = "MVP奖杯")
private String name;

效果图:

6、默认去除小蓝点的版本控制,开发者可以通过在服务端通过配置进行开启,详情请参考增强文档

knife4j:
  enable: true
  setting:
    #是否开启界面中对某接口的版本控制,如果开启,后端接口变化后Ui界面会存在小蓝点
    enableVersion: true 

7、可以通过配置重命名界面Swagger Models的命名,详情请参考增强文档,例如:

knife4j:
  enable: true
  setting:
    enableSwaggerModels: true
    swaggerModelName: 实体类列表

8、可以通过配置是否显示调试栏中的AfterScript功能,该属性默认为true,详情请参考增强文档,例如:

knife4j:
  enable: true
  setting:
    enableAfterScript: false

9、支持@RequestMapping注解中的params参数Gitee #I22J5Q

10、3.0版本不支持Authorize的问题Gitee #I22WVM

11、增加局部刷新变量的按钮功能,可以通过服务端配置开启Gitee #I22XXI,该属性默认为false,详情请参考增强文档,例如:

knife4j:
  enable: true
  setting:
    enableReloadCacheParameter: true

12、修复兼容性bug,当升级后,默认Swagger Models以及文档管理功能丢失的问题

使用方法

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.7</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.1</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.1</version>
</dependency>

特点

  • 基于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

    我有话说:

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

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

    「尝鲜」SpringBoot 快速整合Swagger 3.0

    第一步:Maven引入Swagger3.0 starter依赖 Maven项目中引入springfox-boot-starter依赖: <dependency> <

    smart-doc 2.0.0 重磅发布,Java 零注解 API 文档生成工具

    smart-doc是一款同时支持java restful api和apache dubbo rpc接口文档生成的工具,smart-doc颠覆了传统类似swagger这种大量采用注解侵入来生成文档

    WeCube 2.7.0 版本发布,一站式架构和运维管理工具

    WeCube简介 微众银行在分布式架构实践的过程中,发现将银行核心系统构建于分布式架构之上,会遇到一些与传统单体应用不同的痛点(例如,服务器增多,部署难度大;调用链长,全链路跟踪困难; 系统复杂

    Syncthing 1.11.0 和 1.11.1 发布,连续文件同步工具

    Syncthing 是一个免费开源的工具,它能在你的各个网络计算机间同步文件/文件夹,它的同步数据是直接从一个系统中直接传输到另一个系统的,并且它是安全且私密的。 Syncthing 1

    swagger-admin v1.3.5 已经发布Swagger 文档管理后台

    swagger-admin v1.3.5 已经发布,这是一个Swagger文档管理后台,可统一管理多个项目的Swagger文档,只需要一个Java8环境,下载后即可运行使用。 支持导入json,非

    Hunt Framework 3.4.2 发布,小版本修细节

    优势,比如 Django 的模板引擎和 Mid...

    【开源资讯】phpMyAdmin 4.9.7 和 5.0.4 发布,可视化 MySQL 管理后台

    phpMyAdmin 4.9.7 和 5.0.4 发布了。phpMyAdmin 是一个非常受欢迎的 web MySQL 数据库管理工具。它能够创建和删除数据库,创建/删除/修改表格,删除/编辑/新增

    工具集001

      1.  Google项目管理工具 Tables   2. 终端 taskwarrior --- TODO List Taskwarrior is

    工具集002

      文件对比 https://www.diffchecker.com/excel-diff 快速找出类似文件的不同之处。  

    最全Mac工具

      MacTool Mac 开源免费工具汇总, 只罗列开源好用的。更全列表请参考awesome-mac 必备 Homebrew - 体验通过命令行安装 Mac 软件的工具(大部分是

    开源文档系统 MrDoc 0.6.2 版本发布

    作为个人和小型团队的文档、笔记和知识管理工具,致力...

    TeamCity 2020.2.4 发布,持续集成工具

    TeamCity 2020.2.4 发布了。TeamCity 是一款功能强大的持续集成工具,覆盖服务器端和客户端。它提供一系列特性可以让团队快速实现持续集成:IDE 工具集成、各种消息通知

    Spring Boot 2.4.0-RC1, 2.1.18, 2.2.11 和 2.3.5 发布

    Spring Boot 多个分支发布了新版本,分别是 2.4.0-RC1, 2.1.18, 2.2.11 和 2.3.5。 Spring Boot 2.4.0-RC1 此版本是 

    Spring Cloud Data Flow 2.7.1 发布

    Spring Cloud Data Flow 2.7.1 发布了。Spring Cloud Data Flow 是构建数据集成和实时数据处理流水线的工具包。 主要更新内容 UI 错误修复

    【开源资讯】Spring Boot 2.4.0.M4 发布

    Spring Boot 2.4.0 的第四个里程碑版本发布了,可以从里程碑仓库获取。此版本包含 145 项更新内容,亮点如下:1、改进故障分析器(Failure Analyzer

    phpPgAdmin 7.13.0 发布

    phpPgAdmin 7.13.0版本于今天发布。该版本涉及以下更新: 增加对Postgres 13的支持; 增加对Postgres 14的暂时适配; 升级Jquery库为jquery 3.4.1

    Apache Kafka 2.7.1 发布

    Apache Kafka 2.7.1 已发布,这是一个 bugfix 版本,其中包括来自 45 个 JIRA 的修复和改进,还修复了部分严重的错误。 改进 [KAFKA-10852] - 优化

    「开源资讯」Atom 1.52.0 和1.53.0-beta0发布,跨平台文本编辑器

    Atom 同时发布了 1.52.0 和 1.53.0-beta0 版本。Atom 是 GitHub 专门为程序员推出的一个跨平台文本编辑器。具有简洁和直观的图形用户界面,并有很多有趣的特点:支持