549 Unstar Star 3.1K Fork 712

GVP萧明 / knife4j

2020-09-15 09:53
118100 xiaoym 1578918321 萧明

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

Gitee:https://gitee.com/xiaoym/knife4j

GitHub:https://github.com/xiaoymin/swagger-bootstrap-ui

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

特性 & 优化

1、Ui整体性能优化,主要从以下几个方面展开Gitee #I1TYNK:API 数量50个 操作和切换选项卡 异常卡顿、Gitee #I1LWNM:更新到 2.0.4版本后,接口无法打开、Gitee #I1J52C:knife4j(2.0.2)swagger(2.9.2),离线文档无法使用html下载、GitHub #243:调试功能可否加个开关?能动态打开是否启用调试功能。

  • 获取接口初始化Swagger文档时,只初始化菜单、以及基础信息字段
  • 接口path节点以及Model-definition节点作为异步解析,除了导出功能外只有展示的文档涉及到的信息才会进行解析,缩减没必要的内存开销和空间性能等待
  • SwaggerModels功能中的所有Model通过异步加载,减少内存开销.

2、通过@EnableKnife4j注解注入的实体Bean包含部分Filter,Filter涉及到应用入侵,优化为只有在开发者启用了Knife4j提供的配置值时,该实体Bean才生效

3、解决通过/plus路径来开启增强模式时失效的问题Gitee #I1OJCK:快速访问增强地址时,没有自动启用增强模式

4、接口描述信息支持Markdown语法渲染

5、解决调试发送后,状态栏curl出现参数为null的问题Gitee #I1QC7Z:发送请求参数不写的话为null、Gtiee #I1QXJ1:请问参数支持空字符串传递吗

6、移除fastjson等不必要的依赖Gitee I1OIY9

7、在左侧菜单接口中新增接口类型,并且在分组中显示当前分组下包含的接口数量Gitee #I1PE0H:侧边栏可否同之前一样,直接显示请求类型,如下图:

8、优化在当前分组名称/Controller名称/接口分词中带字符/导致页面空白的问题,如果包含使用字符-进行替换Gitee #I1SMAY:当tags包含/字符时打开接口页面空白

9、Vue以及ant-design-vue版本升级到当前最新版

10、导出的离线Html文档优化属性,去除无效的属性引用导致Html文档文件太大(降低5倍以上).

11、增加导出Word文档的实现

12、返回大数据量造成页面卡死的问题优化Gitee #I1QIJK:调用接口后,返回1万多行数据的json,造成页面卡死

13、优化默认的标题显示,开发者未设置分组服务标题时文档标题默认显示Knife4j 接口文档Gitee #I1P4OQ:页面title如果有配置,初始化时默认“Knife4j接口文档”,然后再变成设置的title值,体验不好,是否去掉?

14、枚举类型针对Array数组类型支持多选Gitee #I1NOTE:enum array 不可多选、GitHub #267:Swagger字段属性说明不显示问题(已阅读https://doc.xiaominfo.com/faq/swagger-des-not-found.html)

15、针对POST、PUT、PATCH等请求方式,以x-www-form-urlencoded请求头发送请求时,请求参数在url追加的问题,以避免请求时400错误的发生.

16、在i18n环境下离线文档导出时没有完全国际化的优化操作Gitee #I1MKP7:离线文档功能bug

17、针对@RequestBody的请求下载接口响应乱码的问题修复Gitee I1U4LA

18、调试返回状态栏数据大小的显示优化B.KB、MBGitHub #264:errorCode

19、支持UiConfiguration中方法调试的配置,如并未配置任何支持的方法,在ui界面中不会出现调试栏TabGitHub #241:接口排序问题,代码如下:

@Bean
public UiConfiguration uiConfiguration(){
    return UiConfigurationBuilder.builder()
        .supportedSubmitMethods(new String[]{})
        .build();
}

20、接口文档中针对请求参数存在示例值的情况下,在接口的参数说明中予以显示GitHub #109:1.8.3版本@RequestParam映射无效

21、去除doc.html对favicon.ico的请求,以避免开发者在网关微服务的架构中集成时出现404.

Last committed message: !25 2.0.5 RELEASED
2020-06-28 12:40
118100 xiaoym 1578918321 萧明

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、支持UiConfiguration中方法调试的配置,如并未配置任何支持的方法,在ui界面中不会出现调试栏Tab,代码如下:

@Bean
public UiConfiguration uiConfiguration(){
    return UiConfigurationBuilder.builder()
        .supportedSubmitMethods(new String[]{})
        .build();
}

2、在当前文档页添加复制接口功能,便于开发人员快速复制接口地址github #238:文件下载名称兼容问题

3、修复Authorize修改或注销的问题gitee #I1IJK3:Authorize 修改或注销的问题(2.0.3)

4、个性化配置新增Host属性的配置,如果当前对外提供的接口文档和接口本身Host属性存在冲突,可以自动配置此属性进行接口的联调,Host属性可以配置为ip:port的形式,这样默认是HTTP进行访问,开发者也可以配置完整的域名或者HTTPS等配置

其工作原理是在调用axios组件进行接口调试时,配置其baseURL属性

var baseUrl='';//默认是空
//是否启用Host
if(this.enableHost){
    baseUrl=this.enableHostText;
}
var requestConfig={
    baseURL:baseUrl,//调用目标Host服务的接口
    url: url,
    method: methodType,
    headers: headers,
    params: formParams,
    data: data,
    //Cookie标志
    withCredentials:this.debugSendHasCookie(headers),
    timeout: 0
}

开发者要使用此Host的配置后端必须开启跨域的配置,如果是Spring Boot,示例代码如下:

@Bean
public CorsFilter corsFilter(){
    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
    CorsConfiguration corsConfiguration=new CorsConfiguration();
    corsConfiguration.setAllowCredentials(true);
    corsConfiguration.addAllowedOrigin("*");
    corsConfiguration.addAllowedHeader("*");
    corsConfiguration.addAllowedMethod("*");
    corsConfiguration.setMaxAge(10000L);
    source.registerCorsConfiguration("/**",corsConfiguration);
    CorsFilter corsFilter=new CorsFilter(source);
    return corsFilter;
}

5、调试接口时,接口在无返回数据或者异常的情况下弹框错误信息,提示开发者

6、图片预览接口无法在响应内容中在线预览图片的问题gitee #I1KP0Q:2.x版本图片预览失效

7、修复针对Map字段时,Value指引是本类时出现递归死循环的问题,结构如下:

"SensorTable": {
            "type": "object",
            "properties": {
                "attrib": {
                    "type": "integer",
                    "format": "int32"
                },
                "sensorMap": {
                    "type": "object",
                    "additionalProperties": {
                        "originalRef": "SensorTable",
                        "$ref": "#/definitions/SensorTable"
                    }
                }
                //more...
            },
            "title": "SensorTable"
        },

8、修复离线文档功能导出Markdown时,响应参数格式异常的问题gitee #I1LMYO:使用knife4j生成的markdown文件 ,其中Response参数缺失type,还有schema为false。

9、修复在使用中间件对接口响应内容进行拦截处理时,响应内容不显示的bug,例如使用sentinel 进行QPS限流,一般在这种情况下是由于接口响应的Content-Type是json,但实际响应内容却是text导致gitee #I1JO73:请求返回BUG

Last committed message: 2.0.4 RELEASED
2020-05-24 16:10
118100 xiaoym 1578918321 萧明

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

特性 & 优化

knife4j

1、读取Markdown文件时,当文件不存在时日志错误信息简化打印,开发者可以忽略该错误gitee #I1E1S1:没有markdown目录会报错

knife4j-spring-ui

1、移除Vue中的pwa机制,解决service-work.js引起的各种问题github #206:响应内容过长时,显示有点乱

2、支持UiConfiguration中方法调试的配置,如并未配置任何支持的方法,在ui界面中不会出现调试栏Tab,代码如下:

@Bean
public UiConfiguration uiConfiguration(){
    return UiConfigurationBuilder.builder()
        .supportedSubmitMethods(new String[]{})
        .build();
}

界面中的显示效果如下(仅显示文档):

3、GET请求出现参数未填的情况下发送Null的buggitee #I1BG4O:String类型默认传参nullgithub #213:接口展示优化建议

4、针对开发者在调试时更改接口地址,在接口地址中添加参数的情况,出现发送请求失败的buggitee #I1C5OQ: 加了额外的参数就识别不了最外层的参数

5、解决集成文档时各种basePath问题导致Ui的logo不显示的问题,通过Base64将logo图片转换处理,img标签直接显示base64字符串gitee #1CQ1F:项目 带了应用名 接口调用失败

6、左侧菜单栏在收缩状态下显示版本控制的标识导致菜单异常的问题,在收缩状态下禁用该项gitee #I1CCXT:左侧菜单有个小buggitee #I1DBDF:未读接口,收起导航显示错误

7、增强功能忽略参数不完全的问题gitee PR#18

8、服务端在没有Write任何数据的情况下,针对非200状态码不显示状态的异常问题gitee #I1BKRH:调试界面响应码404和201不显示

9、针对raw类型的请求接口类型,全局参数中只能是header参数的问题,支持query类型的全局参数gitee #I1C86F:接口参数为json类型,token只能在head中携带,url无法携带token

10、增加对Xml请求的适配支持,服务端consumes属性设为application/xml接口gitee #I1BCKB:不支持application/xml请求,xml入参和xml出参,界面显示的还是json格式

11、增加@ApiSupport注解,分组Controller下可以设置全局author属性,或者order排序属性

12、剔除webjar文件中的favicon.ico文件,以避免和主项目产生冲突gitee #I1ELHN:knife4j-spring-ui-2.0.2.jar!\META-INF\resources\favicon.ico 请问这个图标怎么覆盖?github #215:功能建议,自定义左侧菜单,添加自定文档

13、新增includeParameters属性,开发者可以在文档的参数中新增一种选择,该特性是和ignoreParameters对立,具体可以参考文档

14、优化在editor编辑器中的属性字段显示效果gitee #I1G3G9:请求示例和响应示例以及响应内容的"显示说明"的问题

15、导出的Html、Markdown离线文件添加作者属性gitee #I1EXXO:导出得html文档,没有作者这一栏

16、在Ui的全局参数配置中添加Header类型的请求参数后,非空情况下会自动合并每个接口的Header请求参数,接口中的Header如果和全局参数配置中的Header同名但是为空的情况下,Ui会使用全局参数配置中的Header参数gitee #I1GD87:控制台里的全局参数设置问题

17、优化请求数据类型的显示问题,Ui自动根据参数的类型识别出当前接口的请求类型并进行展示,解决springfox等框架始终解析为json请求的buggitee #I1EMJ9:请求数据类型[ "application/json" ]怎么改?gitee #I1903T:全局设置的consumes不显示

18、修复请求头Content-Type在调试时被忽略的问题,该问题具体参考gitee #I18HGS:设置请求头Content-Type无效,knife4j在2.x版本使用的是axios组件,axios针对发送的请求头data属性如果没有传递的情况下会忽略Content-Type请求头,具体可参考https://github.com/axios/axios/issues/86

19、添加I18n的支持,目前支持的语言:中文、English

20、请求头携带Cookie的情况,如果要使用Cookie,请求头的名称请确保为Cookie,不能有小写或其他.

21、添加对springdoc框架的集成支持

如果你后端是Java+Spring的技术栈,在使用springfox的同时,想换一个Swagger的Ui皮肤,通过在pom.xml中直接引入即可,如下:

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-spring-ui</artifactId>
  <version>2.0.3</version>
</dependency>

后端渲染OpenAPI的解析框架是springdoc,则添加如下依赖引用:

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-springdoc-ui</artifactId>
  <version>2.0.3</version>
</dependency>

Knife4j-Spring

使用Spring Boot的技术栈可以通过引用starter的方式快速引入使用,注意该starter组件是包含Ui的,如下:

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-spring-boot-starter</artifactId>
  <version>2.0.3</version>
</dependency>

如果是微服务的情况下,微服务其实不需要引用Ui的jar包,只需要在网关引用Ui的jar包依赖,所以在微服务情况下,使用增强属性只需要引用微服务版本的starter依赖,如下:

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-micro-spring-boot-starter</artifactId>
    <version>2.0.3</version>
</dependency>

Knife4j-Admin

knife4j-admin是一个基于Spring Cloud Gateway网关,通过网关的特性,结合knife4j对Swagger的文档进行动态聚合的管理平台

平台特点:

  • 跨语言、跨平台
  • 任意聚合Swagger文档,动态发布,调试
  • 文档个性化配置、权限等
  • 彻底告别聚合网关文档等由于软件版本等造成的技术集成问题
  • 独立部署

如果你有以上的需求的话,可以考虑使用一下knife4j-admin这个产品,产品文档点这里

Last committed message: 2.0.3 RELEASED
2020-03-08 19:55
118100 xiaoym 1578918321 萧明

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

特性 & 优化

knife4j

1、新增knife4j-dependencies模块,管理knife4j的相关Maven引用,可以以Maven的BOM方式引入Knife4j

2、官网文档同步更新.

3、解决swagger-annotations导致的版本冲突gitee #I17G31:knife4j-micro-spring-boot-starter自身存在冲突..GitHub #191:调试返回结果缓存问题

knife4j-spring-ui

1、修复切换tab之后 再次发送请求不带参数且不显示响应数据的问题,调试异常等问题PR 13 @Gitee gitee #I17FFX:api 切换请求、响应BUG(2.0.1)GitHub #196:开启生产环境,屏蔽Swagger所有资源接口 建议GitHub #187:点击离线文档导致页面奔溃

2、优化调试框全部选中的问题,在取消全选时,只有在输入参数改变时才会选中该参数,取消原来默认选中全部参数gitee #I19V6D:关于调试时参数勾选问题

3、针对Form表单类型的请求构造curl命令行时在未输入值的情况下为null的情况,修改为空字符串gitee #I18IBZ:2.0.1 不填参数应该传递 "" 或者不传递该参数,而非

4、优化全局参数设置功能,针对参数数据太长不换行问题,以及参数需要修改时需要重新删除的交互体验,开发者在新增参数后可以方便的更改参数数据值以及参数的类型gitee #I17OV1:全局参数不支持修改吗,accessToken过期了 每次要删掉重新创建gitee #I19GJK:全局参数的样式问题gitee #I1A9V1:全局参数设置.字段太长.删除按钮就不见了.但是f12看得到gitee #I18HMJ:强烈建议支持全局参数可以修改,强烈建议全局参数设置后,header中相同的参数不要显示两个GitHub #176:schema下的properties里的ref不能被识别

5、请求参数在未给定example默认值的情况下,文本输入框的placeHolder属性显示该字段的文字说明gitee #I17RKI:参数值名称

6、修复增强属性忽略参数不生效的问题gitee #PR-16gitee #I136KU:请求参数对象忽略指定参数,在请求示例中部分未忽略gitee #I187VN:忽略参数 JsonObject不生效gitee #I16A71:@ApiOperationSupport 无效

7、调试参数框增加对后端枚举的支持,改输入框为下拉选择框gitee #I18MHO:2.0.1 版本可选参数没有旧版本的那种下拉框

8、service-worker.js报404问题,构建打包时添加此文件gitee #I17D0Y:service-worker.js报错GitHub #185:可否将这个ui的依赖包,放到一个空的springboot项目中,只负责ui显示

9、get请求参数出现特殊字符未编码处理导致出现400错误gitee #I19C8Y:get 请求参数未编码

10、后端新增接口或者接口编辑后,在ui界面显示更新标志,在菜单上会出现一个蓝色的徽标gitee #I1AQFW:新接口显示new图标,如下图:

11、后端增强注解@ApiOperationSupport(author = "xiaoymin@foxmail.com")支持每个接口提供开发者的呈现,最终如下图:

12、调试发送按钮增加loading效果,针对接口响应较长的情况下提升交互效果

13、针对Authorize菜单栏的参数,保存参数是全局保存,其它逻辑分组的接口再调试时,不需要再保存一次新值gitee #I16Z10:2.0.0版本,Authorize 设置参数无法统一设置。

14、修复部分情况响应字段在ace-editor编辑器右边栏不显示字段说明的情况gitee #I17F5Y:Knife4j版本字段属性说名缺失问题

15、搜索框完善对接口请求Api地址栏的模糊搜索匹配gitee #I19EN0:新版ui不支持uri索,老版本是支持的gitee #I1B0Q9:Knife4j 2.0.1版本为什么了没有了API地址显示和api地址搜索功能呢?

16、调试响应数据行太长,无法换行的问题gitee #I17F1J: knife4版本相应内容过长不换行

17、在当前接口无参数的情况下,界面添加全局参数无效果的bug

如果你后端是Java+Spring的技术栈,在使用springfox的同时,想换一个Swagger的Ui皮肤,通过在pom.xml中直接引入即可,如下:

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-spring-ui</artifactId>
  <version>2.0.2</version>
</dependency>

Knife4j-Spring

使用Spring Boot的技术栈可以通过引用starter的方式快速引入使用,注意该starter组件是包含Ui的,如下:

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-spring-boot-starter</artifactId>
  <version>2.0.2</version>
</dependency>

如果是微服务的情况下,微服务其实不需要引用Ui的jar包,只需要在网关引用Ui的jar包依赖,所以在微服务情况下,使用增强属性只需要引用微服务版本的starter依赖,如下:

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-micro-spring-boot-starter</artifactId>
    <version>2.0.2</version>
</dependency>

特点

  • 基于Vue+Ant Design构建的文档,更强大、清晰的接口文档说明能力以及接口调试能力
  • 左右布局,基于Tabs组件的多文档查阅风格
  • 支持在线导出Html、Markdown、Word、PDF等多种格式的离线文档
  • 接口排序,支持分组及接口的排序功能
  • 支持接口全局在线搜索功能
  • 提供Swagger资源保护策略,保护文档安全
  • 接口调试支持无限参数,开发者调试非常灵活,动态增加、删除参数
  • 全局缓存调试信息,页面刷新后依然存在,方便开发者调试
  • 以更人性化的table树组件展示Swagger Models功能
  • 文档以多tab方式可显示多个接口文档
  • 请求参数栏请求类型、是否必填着颜色区分
  • 主页中粗略统计接口不同类型数量
  • 支持自定义全局参数功能,主页包括header及query两种类型
  • JSR-303 annotations 注解的支持
  • 更多个性化设置功能
Last committed message: 2.0.2 RELEASED
2019-12-23 10:08
118100 xiaoym 1578918321 萧明

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

文档:http://doc.xiaominfo.com

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

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

**Gitee:**https://gitee.com/xiaoym/knife4j

**GitHub:**https://github.com/xiaoymin/swagger-bootstrap-ui

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

特性 & 优化

knife4j-spring-ui

1、解决x-www-form-urlencoded类型的表单请求,参数勾选复选框无法取消的情况gitee #I16S14:参数选择不了

2、个性化配置中新增是否开启动态参数选项,默认为false,不开启,如果有需要的可以勾选此选项,可以无限动态添加参数进行接口调试

3、实现全局搜索功能gitee #I16ZW4:2.0.0版本,全局搜索按钮消失

4、@deprecated 标记的接口置为过时gitee #I1736T:2.0.0 版本, @Deprecated 标记的接口,没有显示 删除线 了

5、针对返回的数据太大,导致页面卡死的情况下,界面做限制处理,如果返回的数据大于2M,不进行格式化处理,弹出提示,提醒开发者在raw进行响应内容的查看,只显示纯文本gitee #I16ZV4:2.0.0 版本,数据量大前端卡死

6、优化响应数据大小的格式化显示,BYTE\KB\MB

7、实现图片预览功能gitee #I173AN:2.0.0 版本, 图片无法预览?

如果你后端是Java+Spring的技术栈,在使用springfox的同时,想换一个Swagger的Ui皮肤,通过在pom.xml中直接引入即可,如下:

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-spring-ui</artifactId>
  <version>2.0.1</version>
</dependency>

Knife4j-Spring

使用Spring Boot的技术栈可以通过引用starter的方式快速引入使用,注意该starter组件是包含Ui的,如下:

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-spring-boot-starter</artifactId>
  <version>2.0.1</version>
</dependency>

如果是微服务的情况下,微服务其实不需要引用Ui的jar包,只需要在网关引用Ui的jar包依赖,所以在微服务情况下,使用增强属性只需要引用微服务版本的starter依赖,如下:

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-micro-spring-boot-starter</artifactId>
    <version>2.0.1</version>
</dependency>

Last committed message: 2.0.1 RELEASED
2019-12-16 09:39
118100 xiaoym 1578918321 萧明

Knife4j前身是swagger-bootstrap-ui,取名knife4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍,更名也是希望把她做成一个为Swagger接口文档服务的通用性解决方案,不仅仅只是专注于前端Ui前端.虽然目前还只是在前端,但以后功能肯定不止于此.

2.0版本主要是使用Vue+Ant Design Vue对前端Ui进行重写,该版本是真正的前后端分离版本,同时依赖于Vue的技术生态,以后会有更多有趣的功能实现,全方位满足开发者的需要.

文档:http://doc.xiaominfo.com

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

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

Gitee:https://gitee.com/xiaoym/knife4j

GitHub:https://github.com/xiaoymin/swagger-bootstrap-ui

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

特性 & 优化

knife4j-spring-ui

1、使用Vue+Ant Design Vue对Ui进行重写,统一整体界面风格,更清晰的文档说明能力以及接口调试能力

2、支持在界面中导出离线Markdown、离线Html格式的文档,Markdown、Html风格较之前都做了极致的优化,Markdown格式主要是针对树形Model的展示通过缩进的方式在md格式的table中显示更加直观,Html离线文档和在线版风格几乎没有区别,简洁、直观.点击预览导出离线Html效果

3、单接口文档页的复制文档也是通过复制Markdown格式的问题,同上主要优化md格式的table显示问题,以缩进的方式显示树形表格

4、对调试栏进行优化、区分请求头和请求体参数,使用tab标签页组件可以对请求参数进行动态的添加、维护、如果你使用对文档进行缓存,文档页的动态调试参数会持久化处理.

5、文档的个性化配置(增强功能)有删减,目前只保留4项功能,即(请求参数缓存、过滤重复同类型接口、本地缓存打开tab接口、文档增强)

6、Tab标签页打开接口、右键可以根据选择关闭不同的Tab标签页

7、调试框请求头、请求体均支持动态参数,开发者可以自行添加动态参数进行调试,更加灵活方便

8、提供增强直接访问地址,http://ip:port/doc.html#/plus,后端在保证开启增强注解的情况下可直接使用该地址,不需要在前端个性化配置中再进行配置,方便团队直接进行沟通

9、响应下载类型增加至141种,几乎涵盖目前常见的文件类型

10、修复响应体中会出现属性多余双引号的buggitee # I125B2、github #156:建议敲回车时,直接提交

11、修复请求参数数据类型的format不显示的问题,针对Long类型区分int64、int32- github #161:响应状态返回不正确

12、解决多个Schema响应状态码的情况下SwaggerModels字段不显示的问题github #170:请求示例文本框显示不完整

13、调试请求默认追加一个Ui的请求头Request-Origion,值为Knife4j,原来该值是SwaggerBootsrapUi,在2.0版本中进行了变更.

14、解决Models属性嵌套过多时,页面白板,效率问题github #106:同时传输文本信息和文件时,值重复

如果你后端是Java+Spring的技术栈,在使用springfox的同时,想换一个Swagger的Ui皮肤,通过在pom.xml中直接引入即可,如下:

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-spring-ui</artifactId>
  <version>2.0.0</version>
</dependency>

Knife4j-Spring

1、移除增强注解@EnableSwaggerBootstrapUi,以后的增强开启注解请使用@EnableKnife4j

2、knife4j-spring-boot-starter组件移除默认springfox的ui-jar包springfox-swagger-ui,只保留knife4j-spring-ui,开发者如果要使用springfox的ui包需要自行在项目中引入

3、合并PR12-修复IDEA debug无法显示动态Response的问题,修复动态类加载不到的问题

使用SpringBoot的技术栈可以通过引用starter的方式快速引入使用,注意该starter组件是包含Ui的,如下:

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-spring-boot-starter</artifactId>
  <version>2.0.0</version>
</dependency>

如果是微服务的情况下,微服务其实不需要引用Ui的jar包,只需要在网关引用Ui的jar包依赖,所以在微服务情况下,使用增强属性只需要引用微服务版本的starter依赖,如下:

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-micro-spring-boot-starter</artifactId>
    <version>2.0.0</version>
</dependency>

特点

  • 基于Vue+Ant Design构建的文档,更强大、清晰的接口文档说明能力以及接口调试能力
  • 左右布局,基于Tabs组件的多文档查阅风格
  • 支持在线导出Html、Markdown、Word、PDF等多种格式的离线文档
  • 接口排序,支持分组及接口的排序功能
  • 支持接口全局在线搜索功能
  • 提供Swagger资源保护策略,保护文档安全
  • 接口调试支持无限参数,开发者调试非常灵活,动态增加、删除参数
  • 全局缓存调试信息,页面刷新后依然存在,方便开发者调试
  • 以更人性化的table树组件展示Swagger Models功能
  • 文档以多tab方式可显示多个接口文档
  • 请求参数栏请求类型、是否必填着颜色区分
  • 主页中粗略统计接口不同类型数量
  • 支持自定义全局参数功能,主页包括header及query两种类型
  • JSR-303 annotations 注解的支持
  • 更多个性化设置功能
Last committed message: 效果图
2019-08-29 10:05
118100 xiaoym 1578918321 萧明

swagger-bootstrap-ui 1.9.6 发布了。swagger-bootstrap-ui是 Swagger 的增强UI 实现,使文档更友好一点儿

文档:http://doc.xiaominfo.com

效果:http://swagger-bootstrap-ui.xiaominfo.com/doc.html

Gitee:https://gitee.com/xiaoym/swagger-bootstrap-ui

GitHub:https://github.com/xiaoymin/swagger-bootstrap-ui

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

重要说明

这是swagger-bootstrap-ui的最后一个版本

这是swagger-bootstrap-ui的最后一个版本

这是swagger-bootstrap-ui的最后一个版本

重要的事情说三遍!!!

一开始项目初衷是为了写一个增强版本的Swagger 前端UI,但是随着项目的发展,面对越来越多的个性化需求,不得不编写后端Java代码以满足新的需求,在swagger-bootstrap-ui的1.8.5~1.9.6版本之间,采用的是后端Java代码和Ui都混合在一个Jar包里面的方式提供给开发者使用.这种方式虽说对于集成swagger来说很方便,只需要引入jar包即可,但是在微服务架构下显得有些臃肿。

因此,项目正式更名为knife4j,取名knife4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍,更名也是希望把她做成一个为Swagger接口文档服务的通用性解决方案,不仅仅只是专注于前端Ui前端.

swagger-bootstrap-ui的所有特性都会集中在knife4j-spring-ui包中,并且后续也会满足开发者更多的个性化需求.

主要的变化是,项目的相关类包路径更换为com.github.xiaoymin.knife4j前缀,开发者使用增强注解时需要替换包路径

后端Java代码和ui包分离为多个模块的jar包,以面对在目前微服务架构下,更加方便的使用增强文档注解(使用SpringCloud微服务项目,只需要在网关层集成UI的jar包即可,因此分离前后端)

knife4j沿用swagger-bootstrap-ui的版本号,第1个版本从1.9.6开始,关于使用方法,请参考文档

由于更名给大家带来的不便深表歉意~!

特性&优化

1、解决Spring路由PathVariable不显示的情况,并优化交互体验

2、解决响应体中的长整型显示错误,精度丢失的问题#135:swagger ui框架的model显示功能建议 @adminchen

3、优化请求头Header是中文的情况,如果包含中文则进行encodeURI函数处理,否则不做任何处理#140:图片预览不能显示 @adminchen

4、升级jQuery 1.X系列版本到最新版本1.12.4

5、初始化页面请求Swagger接口资源方式改为异步,在jQuery的ajax方法参数项async:false时,浏览器会抛出警告的问题(同步ajax请求会造成主线程阻塞,对用户体验不是很好,已被置为过时).

6、支持supportedSubmitMethods,后端配置UiConfiguration的Bean#IVCQ0 @Gitee

7、优化下载中文乱码问题,后端需要指定filename值,并且对名称进行URLEncoder.encode处理,UI前端会进行decode成中文,保证下载正常

8、修复curl状态栏复制时内容被转义的bug#136 @adminchen

Maven坐标

<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.6</version>
</dependency>
2019-07-31 21:13
118100 xiaoym 1578918321 萧明

swagger-bootstrap-ui 1.9.5 发布了。swagger-bootstrap-ui是 Swagger 的增强UI 实现,使文档更友好一点儿

文档:http://doc.xiaominfo.com

效果:http://swagger-bootstrap-ui.xiaominfo.com/doc.html

Gitee:https://gitee.com/xiaoym/swagger-bootstrap-ui

GitHub:https://github.com/xiaoymin/swagger-bootstrap-ui

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

特性&优化

1、针对文件上传响应JSON内容时,内容不高亮的问题#IYXZB:响应内容无高亮 版本1.94 @Gitee

2、文件上传响应内容显示异常Bug#IYO96 @Gitee

3、针对中文请求头使用encodeURIComponent()函数进行编码处理#IYMUF:请求头有中文报错 @Gitee

4、修复开启增强时空指针异常Bug#IYADU @Gitee

5、针对@ResponseHeader注解未显示Bug#IY86A @Gitee

6、DELETE请求针对Array类型的请求参数错误Bug#IY37Z @Gitee

7、修复GET请求时CURL响应栏参数拼装错误#131:是否可以添加一个变量之类的,自定义一下调试功能的显示? @adminchen

8、修复非200状态码响应内容不格式化高亮的问题#130:接口入参: list 点击增加 按钮,无效 @adminchen

9、解决地址显示的BUG, 确保请求能够正确发送出去#PR108 @adminchen

10、在使用动态扩展字段说明时,服务器上部署会造成空指针异常,该错误是由未对field名称进行非空判断导致#IYLVC:项目启动报空指针异常 @Gitee、#119 @adminchen

11、可以自定义动态过滤请求参数,这在很多时候可以让我少写实体类,比如新增的时候不需要id,修改时又需要id,只需要在接口层使用增强注解@ApiOperationSupport的ignoreParameters属性即可,具体使用规则请参考文档

12、优化增强排序接口注解@ApiSort无效果的问题

13、响应类Model动态添加解释字段.请参考文档

Maven坐标

<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.5</version>
</dependency>
Last committed message: 1.9.5 RELEASED
2019-06-10 17:14
118100 xiaoym 1578918321 萧明

swagger-bootstrap-ui 1.9.4 发布了。swagger-bootstrap-ui是 Swagger 的增强UI 实现,使文档更友好一点儿

文档:http://doc.xiaominfo.com

效果:http://swagger-bootstrap-ui.xiaominfo.com/doc.html

Gitee:https://gitee.com/xiaoym/swagger-bootstrap-ui

GitHub:https://github.com/xiaoymin/swagger-bootstrap-ui

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

特性&优化

1、最低需要JDK 1.8支持

2、单独接口通过hash地址访问,方便开发人员之间快速复制传递接口信息,能准确定位到接口

3、优化下载参数名称问题,忽略filename大小写敏感#IXA5C:文件下载名称兼容问题 @Gitee

4、优化BasicFilter过滤器正则匹配频率问题,decode函数调用替换为JDK 1.8版本中的java.util.Base64

5、tab操作项修改为点击事件显示,避免同调试按钮冲突导致误关选项卡#IXA5I:右侧关闭tab菜单优化 @Gitee

6、增加调试接口响应类型为Xml、Html、Text的支持#IWP49:返回xml格式报错 @Gitee

7、优化调试后header、raw、curl等选项卡高度太低的问题#IWLSU:当返回值只有一行时header的高度太窄 @Gitee

8、主页简介description字段支持markdown格式#IVVRX:description不支持MarkDown语法 @Gitee

9、针对枚举类型的集合类型(List),在字段描述中显示枚举可用列表值#100:v1.8.2的 parameters 如果in参数是formData时, 字段是否填写判断有问题么? @adminchen

10、重构原接口排序、tag排序规则,新增接口作者属性,可写每个接口的作者,方便开发者调试.参考文档

11、针对Authorize授权的相关属性,不同分组相同的请求参数只需授权一次即可则全局通用#IXHBL @Gitee

12、针对Map、JSONObject等动态类型可通过自定义注解@ApiOperationSupport或者@DynamicParameters来增加参数的字段说明,解决不想写实体类的烦恼,但是又无文档的困扰.参考文档

13、优化自定义文档(markdown)界面效果,增加相关markdown语法样式(引用editormd.css)

2019-04-23 16:50
118100 xiaoym 1578918321 萧明

swagger-bootstrap-ui 1.9.3 发布了。swagger-bootstrap-ui是 Swagger 的增强UI 实现,使文档更友好一点儿

文档:http://doc.xiaominfo.com

效果:http://swagger-bootstrap-ui.xiaominfo.com/doc.html

Gitee:https://gitee.com/xiaoym/swagger-bootstrap-ui

GitHub:https://github.com/xiaoymin/Swagger-Bootstrap-UI

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

特性&优化

1、增加i18n国际化支持(中文、English),可参考文档

2、优化调试框请求参数类型,添加数据类型issue #IVF2L:调试模块的参数类型显示错误 @Gitee

3、接口描述支持Html渲染issue #IVBWM:接口描述是否不支持html渲染 @Gitee

4、允许添加自定义文档(以markdown的形式)issue #IUWN9:功能建议,自定义左侧菜单,添加自定文档 @Gitee,可参考文档

5、优化非200状态码调试栏显示高度过低的情况.

6、分组tag名称很长时超出bug,增加菜单title鼠标悬浮显示分组tag名称issue #IVE0S:api文件名称过长会换行 @Gitee

7、初始化请求异常处理,弹出友好提示信息.

8、接口任何信息变更和新增接口一样,添加new的icon图表样式,代表当前接口信息已产生变化.

9、Swagger Models中的属性类显示readOnly|example属性issue #77:1.8.1文件上传的bug @adminchen

Bug修复

1、解决多个api文档切换时,Authorize的参数没有变更的bugissue #IV3OZ:多个api文档切换时,Authorize的参数没有变更 @Gitee

2、解决Basic认证出现的空指针异常以及账户密码为空的时候,页面崩溃的情况issue #78:全局参数与接口参数相同时会出现两个 相同参数 并且某一个为空 如图 @adminchen

Last committed message: 1.9.3.RELEASED
2019-04-08 08:51
118100 xiaoym 1578918321 萧明

swagger-bootstrap-ui 1.9.2 发布了。swagger-bootstrap-ui是 Swagger 的增强UI 实现,使文档更友好一点儿

GitHub Gitee 文档 示例代码 在线体验

主要更新如下:

特性&优化

1、增加地址栏参数访问,快速个性化设置功能,可参考文档

2、修改SecurityConfiguration中关于Environment的注入方式,改为属性注解注入,提供默认无参构造,避免某些情况下使用SpringAop导致异常issue #ITI1C:SecurityConfiguration类没有默认构造方法导致出现SpringCGLIB错误 @Gitee

3、针对存在format属性字段类型,显示format属性,使参数更加清晰明了(例如:Integer-int32,Integer-int64,string-date)issue #ITIPQ:datatype类型建议是啥就是啥,不做转换,比如integer就显示integer,不展示为int(32) @Gitee

4、针对body类型的Array类型请求,给与默认参数值issue #ITVZ2:请求参数为数组时,设置example,不显示,请求示例中为[null] @Gitee

5、优化新接口图标太大的问题,解决下拉框选择分组后,title标题属性不切换的问题.issue #IUGWF:提两个优化建议 @Gitee

6、当请求参数太多(>5)时,调试栏显示折叠栏,点击发送后可自动折叠参数

7、图片预览显示高度自适应issue #72:升级到1.8.1后,火狐浏览器无法显示文档 @adminchen

8、针对@RequestBody类型的参数类型枚举的支持issue #73:运行demo出错 @adminchen

9、提供前后端分离的文档预览解决方案,具体参考文档

Bug修复

1、修复请求示例中支持readOnly属性issue #IS28O:example不显示 @Gitee

2、修复响应返回数据的Map类型数据无法展开显示issue #IUAXW:响应返回数据的Map类型数据无法展开显示&Deprecated的api能否加个标识? @Gitee

3、修复点击复制文档,复制的md文件中,没有接口名称issue #71:List<String>和String[]类型解析不正确,应该为array,实际为String并且不能增加 @adminchen

Last committed message: 文档完善
2019-03-11 11:27
118100 xiaoym 1578918321 萧明

swagger-bootstrap-ui 1.9.1 发布了。swagger-bootstrap-ui是 Swagger 的增强UI 实现,使文档更友好一点儿

GitHub Gitee 文档 示例代码 在线体验

主要更新如下:

特性&优化

1、优化大数据响应接口,UI渲染卡顿,导致浏览器崩溃

2、ApiInfo.description支持htmlissue #65:1.8.0窗口大小改变后,界面混乱 @adminchen

3、合并pr#61,优化array子类型为基础类型时schema显示为空的情况

4、响应数据编辑器增加换行模式,针对响应某个字段特别长时,自动换行.

Bug修复

1、关闭默认响应状态后,自定义了@ApiResposes后,字段属性说明不显示issue #IRV1I:关闭默认响应状态后,自定义了@ApiResposes后,字段属性说明不显示 @Gitee

2、example不显示,支持readOnly属性issue #IS28O:example不显示 @Gitee

3、修复Authorize缓存bugissue #ITAST:Authorize出现缓存bug @Gitee

项目地址

Maven坐标

<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.1</version>
</dependency>

码云:https://gitee.com/xiaoym/swagger-bootstrap-ui

GitHub:https://github.com/xiaoymin/Swagger-Bootstrap-UI

在线体验:http://swagger-bootstrap-ui.xiaominfo.com/doc.html

项目文档:http://www.xiaominfo.com/swagger-bootstrap-ui/

Last committed message: 1.9.1 released
2019-02-25 08:48
118100 xiaoym 1578918321 萧明

主要更新如下:

特性&优化

1、优化未给与tags分组时,Ui默认赋值default.

2、针对使用SwaggerBootstrapUi的增强排序功能时导致升级Springfox-Swagger必须升级到2.9.2引起的jar包冲突版本问题,Ui做向下兼容处理,Springfox-Swagger版本最低兼容2.7.0(相对稳定版本,亲测可用)

3、个性化新增配置,是否开启缓存已打开的api文档,感谢@web-xiaxia提交的pr

4、优化application/octet-stream下载出现的参数(header|query)问题

5、优化图片验证码显示问题,可参考文档文件下载及图片预览

6、新增权限特性属性swagger.production,开启此属性后会屏蔽swagger所有访问资源,可用于生产环境中部署屏蔽文档输出.保护文档安全,可参考文档访问权限控制

7、针对Swagger资源请求,提供Basic认证功能,可用于保护Swagger文档页面.可参考Basic详情

8、优化文件上传参数类型File的支持.可参考文档文件上传

9、优化响应数据右侧存在字段说明Span元素重叠,并增加Toggle开关显示关闭右侧字段说明

10、优化离线文档预览,超出UI默认接口数量(100个)时,自动显示markdown源文件代码,供开发者自动复制到第三方转换软件查看,不再提供预览效果

Bug修复

1、启用UI增强时,获取不到WebApplicationContext对象造成空指针异常

2、修复SpringMvc启用增强失败的Bug

3、修改对象属性设置example导致解析Model失败的bugissue #IROVN:引用对象不展示的问题 @Gitee

4、修复搜索后,相关个性化状态设置不显示的bugissue #IRE8W:搜索完后,原先设置的显示中文显示不了 @Gitee

5、修复 请求响应实体类内有Map类型参数无法正常显示 issue #IR61U:请求响应实体类内有Map类型参数无法正常显示 @Gitee

2019-01-11 17:30
118100 xiaoym 1578918321 萧明

Swagger-Bootstrap-Ui 1.8.9 发布了。Swagger-Bootstrap-Ui是 Swagger 的增强UI 实现,目的是替换 Swagger 默认的 UI 实现 Swagger-UI,使文档更友好一点儿

Swagger-Bootstrap-Ui 1.8.9 主要更新如下:

特性&优化

1、主页面添加页面不缓存元素,防止版本升级缓存造成新功能加载失败.

2、响应示例说明、调试响应内容行添加description说明字段,免去切换到文档说明看字段说明的麻烦,非常感谢@wanyaxing提交的PR

3、新增个性化配置-开启RequestMapping接口类型重复地址过滤,默认只显示POST类型的接口地址(针对RequestMapping的接口请求类型,在不指定参数类型的情况下,如果不过滤,默认会显示7个类型的接口地址参数,如果开启此配置,默认展示一个Post类型的接口地址)

4、针对application/octet-stream类型的接口提供下载调试.

Bug修复

1、启用UI增强时,获取不到WebApplicationContext对象造成空指针异常

2、修复list套list的返回值会不显示issue #55:如何将多个微服务的api整合到一个地址里面? @adminchen

3、接口请求参数同全局参数配置名称存在冲突的情况下,根据名称匹配导致参数丢失,匹配规则为参数名称、参数类型同时比较issue #IQV1U:参数丢失(全局里定义一个header的参数为uid,然后接口里有个uid,然后在请求参数里接口的uid不见了。) @Gitee

4、服务端响应HTML标签数据时,响应内容显示异常issue #IQ9LG:请求返回带<img标签时,不显示 @Gitee

5、修复参数格式问题issue #IPXX7:模拟请求的参数格式不对,字符串变成了数字 @Gitee

6、针对多响应码返回不同schema类型,离线文档(markdown)未展示完整的bugissue #IPPHJ:响应状态返回不正确 @Gitee

项目地址

Maven坐标

<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.8.9</version>
</dependency>
Last committed message: 1.8.9 released
2018-12-17 14:56
118100 xiaoym 1578918321 萧明

Swagger-Bootstrap-Ui 1.8.8 发布了。Swagger-Bootstrap-Ui是 Swagger 的增强UI 实现,目的是替换 Swagger 默认的 UI 实现 Swagger-UI,使文档更友好一点儿

Swagger-Bootstrap-Ui 1.8.8 主要更新如下:

特性&优化

1、顶部标题可自定义,去除原默认显示swagger-bootstrap-ui的固定标题,title规则为获取分组对象apiInfo中的第一个title属性

2、个性化配置中新增是否开启请求参数缓存策略,默认为true,当设置为false时,请求的参数不会再本地产生缓存,下次打开接口调试时需要自己重新输入相关接口参数

3、分组加载由同步改为异步加载

4、新增接口高亮显示,当后端新增接口后,UI会自动标识该接口为新接口,直到该接口被点击为止.

5、当服务器正在重启或者宕机时,接口发生异常,给出友好提示,告知接口对接人员.

6、请求参数必填排序,require=true排最前

7、后端接口方法上针对@Deprecated标注的接口,UI以中横线标注区分

8、针对不同状态响应码,返回内容均有Schema的情况下,UI以tab方式将所有状态码的schema内容呈现

9、优化接口数量过多的情况下,离线文档会导致文档页假死

Bug修复

1、修复针对Delete请求,使用@RequestBody注解出现400错误 issue IPLJT @Gitee

2、修复响应状态码HTML标签非转义输出 issue #47:请问作者,这个支持swagger的OAuth2相关的操作吗? @adminchen

3、不能正确解析response内非$ref的schema内容 issue #43:参数对象里属性加了required=true,文档上是否必须列依然是false @adminchen

项目地址

Maven坐标

<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.8.8</version>
</dependency>
Last committed message: 标题修改
2018-11-11 22:38
118100 xiaoym 1578918321 萧明

Swagger-Bootstrap-Ui 1.8.7 发布了。Swagger-Bootstrap-Ui是 Swagger 的增强UI 实现,目的是替换 Swagger 默认的 UI 实现 Swagger-UI,使文档更友好一点儿

从1.0到更新至今,Swagger-Bootstrap-Ui也新增了很多小特性,为使更多人了解她,我重写了一份关于Swagger-Bootstrap-Ui的文档说明.希望越来越多使用她的用户都能体验到她带来的便利.详情可关注README.MD

Swagger-Bootstrap-Ui 1.8.7 主要更新如下:

特性&优化

1、优化调试框响应内容高度,根据响应内容自动设置响应高度,不再设固定高度.

2、Authorize功能提供注销功能,清空当前缓存在浏览器的相关Auth信息.

3、新增Swagger Models菜单项功能,以TreeTable的方式展示当前Swagger分组实例文档中所有相关的Models属性说明.

4、个性化配置项新增是否显示tag分组description属性的选择项,勾选后,会和swagger官方文档一样显示description属性,默认为false不显示.

5、引入async.js异步组件库,优化文档解析效率,解析渲染速度提升5倍以上.

6、优化接口的id生成策略,使用MD5针对接口地址和mehtod方式生成接口id,调试参数全局缓存localStorage对象中,方便下次刷新访问调试.

7、响应状态栏增加全屏icon,点击全屏icon可全屏查看响应内容.

8、解决离线文档再开启UI增强功能后不排序的问题

9、调试框根据Swagger接口参数显示当前接口的Content-Type类型,在某些特殊情况下可更改默认定义Content-Type请求头类型,如果使用UI提供的全局参数功能,自定义了Content-Type的请求头,则默认以全局参数中的Content-Type为主.

10、增加对JSR-303 annotations 注解的支持(部分)

Bug修复

1、针对SpringCloud通过网关构建Swagger分组获取不到Documentation对象的情况,根据default再获取一次

2、修复UI增强关于使用@Api注解tags属性不赋值,使用value,增强排序失败的问题.

3、修复针对@RequestMapping注解无value属性,UI增强出现数组越界的问题

4、修复针对扩展Spring的RequestMappingHandlerMapping自定义实现方式,获取不到扩展接口url地址信息,导致UI增强排序失败的问题.

项目地址

Maven坐标

<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.8.7</version>
</dependency>
Last committed message: 1.8.7 released
2018-10-31 13:46
118100 xiaoym 1578918321 萧明

swagger-bootstrap-ui 1.8.6 发布了。swagger-bootstrap-ui 是 Swagger 的增强UI 实现,目的是替换 Swagger 默认的 UI 实现 Swagger-UI,使文档更友好一点儿

swagger-bootstrap-ui 1.8.6 主要更新如下:

特性增加

1、请求参数类型(header|body|query)等以不同颜色着色区分

2、调试栏针对必须项(require=true)时,文本框着红色以区分

3、调试页输入框可通过tab键自动切换上下级输入框.

Bug修复

1、修复Spring使用cglib生成的代理类,导致class无法获取Spring的相关注解,导致接口增强排序失败

2、针对basePath属性不是根路径“/”,导致接口排序比对失败,无法排序的问题

3、修复针对SpringCloud通过zuul路由组件加载swagger接口存在basePath属性,增强接口缺失basePath属性的bug,导致增强接口请求失败的问题

4、修复Spring的请求地址仅支持value属性,不支持path属性的bug

5、针对请求头Content-Type中多余空格问题,部分接口调用失败的问题

6、修复针对参数、参数说明太长,导致table换行,样式失效问题.

7、修复针对header、path等参数外,传参只包含body类型无请求json示例的问题.

8、修复针对请求参数存在多个数组,增加按钮无效的BUG.

9、优化离线文档相关的显示格式问题.包括JSON显示格式错乱、添加请求JSON示例、文档开始说明等信息

UI效果展示

Maven坐标

<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.8.6</version>
</dependency>
Last committed message: 1.8.6 released
2018-10-16 10:13
118100 xiaoym 1578918321 萧明

swagger-bootstrap-ui 1.8.5 发布了。swagger-bootstrap-ui 是 Swagger 的增强UI 实现,目的是替换 Swagger 默认的 UI 实现 Swagger-UI,使文档更友好一点儿

swagger-bootstrap-ui在1.8.5以后,她不在是一个纯webjar的UI工具了,她增强了swagger的一些功能支持,例如tags、接口的排序,一些个性化的支持,目前只增强接口排序

后续更多关于swagger的增强功能需求非常欢迎大家提issue反馈,让这款UI更加丰富强大.

swagger-bootstrap-ui 1.8.5 主要更新如下:

1、fixed formdata类型参数针对array数组类型无增加按钮

2、fixed 响应内容高度占比,参数过多的情况无法显示

3、多选项卡文档介绍、在线调试position位置引起的不适改动,由竖变横.

4、增强排序功能,添加个性化配置管理功能,可开启个性化配置

5、关于个性化增强功能,目前已经实现了tags、和接口api方法的排序,使用方式:

在原EnableSwagger2注解上增加@EnableSwaggerBootstrapUi注解

@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class SwaggerConfiguration {
 	//more...   
}

针对tags分组排序,UI的排序规则是顺序排序,最小值1,最大值也是默认值Integer.Max_VALUE;

如果不使用SwaggerBootstrapUi的增强功能,则无需开启@EnableSwaggerBootstrapUi注解

tags的排序规则分两种

a、一种是判断Swagger的@Api注解的position属性是否不等于0(默认值为0),如果该值不为空,则获取此值,根据该值排序

b、如果postion=0(不写的情况下),判断是否存在注解@ApiSort的值,如果有值,则获取此值,根据该值排序

c、所以排序的取值规则是:position>@ApiSort

接口api的排序规则

a、判断@ApiOperation注解上的postion属性是否不等于0(默认值为0),如果该值不为空,则获取此值,根据该值排序

//postion属性赋值
@ApiOperation(httpMethod = "POST",position = 2,value = "Test2Model测试数组参数,多个",response=Test2Model.class)
@ApiResponses({
    @ApiResponse(code = 200, message = "非HTTP状态码,返回值JSON code字段值,描述:成功")
})
@ApiImplicitParams({
    @ApiImplicitParam(name = "ids",paramType ="form",value = "参数",allowMultiple = true, required = true)
})

b、如果postion=0(不写的情况下),判断是否存在注解@ApiOperationSort的值,如果有值,则获取此值,根据该值排序

c、所以排序的取值规则是:position>@ApiOperationSort

注意

注解@EnableSwaggerBootstrapUi@ApiSort@ApiOperationSort是本UI工具包提供的Java注解,排序功能的使用需要在启用原EnableSwagger2注解上增加@EnableSwaggerBootstrapUi注解方可生效

6、默认去除接口api地址的线上,默认只显示方法类型、方法说明两个属性,当然,新版本增加的个性化的配置功能,如果你觉得api地址显示任然有需要,可在个性化配置中开启该功能,个性化配置属性存储在localStorage对象中.只需要配置一次接口.

7、fixed 构建curl功能中写死http,根据window.location.href动态判断(http|https)的情况

8、如果请求参数是json参数body类型,文档说明中添加请求示例json展示,方便查看

9、请求示例、响应示例json自动适配高度

10、选中接口api菜单时,菜单显示激活色,显示背景颜色background-color: #eee;

11、fixed 离线文档markdown格式错乱问题(table标题换行导致显示异常)

12、离线文档已预览html的方式展现,复制文档功能依然是复制markdown语法

13、请求参数及响应参数说明改为多行显示,超出长度不以省略号显示,防止出现浮层一直显示的bug

Maven坐标

<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.8.5</version>
</dependency>
Last committed message: change chines comment
2018-09-25 14:01
118100 xiaoym 1578918321 萧明

swagger-bootstrap-ui 1.8.4 发布了。swagger-bootstrap-ui 是 Swagger 的前端 UI 实现,目的是替换 Swagger 默认的 UI 实现 Swagger-UI,使文档更友好一点儿

swagger-bootstrap-ui 1.8.4 主要更新如下:

1、fixed key-value表单请求 @RequestParam映射无效,在线调试bugissue #IMXOV:1.8.3版本@RequestParam映射无效 @Gitee issue #30:使用聚合文档在线调试都是500错误 @adminchen

2、fixed 树形model默认展开issue #IMXH5:树形model默认展开 @Gitee

3、fixed 两个list里放同一个bean,一个显示一个不显示issue #IMXOY:两个list里放同一个bean,一个显示一个不显示 @Gitee

4、fixed 同时传输文本信息和文件时,值重复issue #IMXDT:同时传输文本信息和文件时,值重复 @Gitee

5、fixed issue #IN03Q:接口调试的时候,1.8.3版本报url参数必填,1.8.2版本报post参数必填(实际已填)。

6、fixed 响应类 3层嵌套解析不出来issue #IMXOF:响应类 3层嵌套解析不出来 @Gitee

7、fixed 全局参数设置接口中已有变量,会导致在线调试里面出现2个参数,不方便调试(如果后端swagger配置文件中使用globalParameter设置全局参数,并且赋予默认值,则以后端全局参数值为准)issue #IMXVD:全局参数设置接口中已有变量,会导致在线调试里面出现2个参数,不方便调试 @Gitee

8、fixed ["text/plain"] controller接收问题issue #IN0PC:["text/plain"] controller接收问题 @Gitee

9、优化调试页响应高度,ace-editor响应高度

10、默认在Swagger-bootstrap-ui的请求,UI会增加一个默认的请求头Request-Origion:SwaggerBootstrapUi

11、fixed Authorize默认tab不选中的bug

12、fixed curl响应参数,针对中文urlencode处理

Maven坐标

<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.8.4</version>
</dependency>
Last committed message: 删除无效js
2018-09-17 12:47
118100 xiaoym 1578918321 萧明

swagger-bootstrap-ui 1.8.3 发布了。swagger-bootstrap-ui 是 Swagger 的前端 UI 实现,目的是替换 Swagger 默认的 UI 实现 Swagger-UI,使文档更友好一点儿

swagger-bootstrap-ui 1.8.3 主要更新如下:

1、新增tab选项卡,各个api接口详情通过新开选项卡来展现

2、去除原schema表格形式展示,请求参数、响应参数改由treetable组件(树组件)展示

3、fixed 请求参数有array类型,显示为schema类型的bug

4、fixed springcloud zuul 整合ui情况下 地址多个/ISSUE #IMF0L:springcloud zuul 整合ui情况下 地址多个/ @Gitee

5、响应内容去除cookies选项卡,响应示例、响应内容使用ace-editor展示响应内容,方便复制

6、优化(全局参数&Authorize)加入浏览器缓存问题,使用localStorage对象全局存储issue #IMH77:全局参数加入浏览器缓存问题 @Gitee

7、fixed 泛型数据接口返回list类型时,不能解析issue #26:Result<T>这种统一相应实体希望能支持 @adminchen

8、fixed 模型内部包含模型没有展示issue #25:globalResponseMessage 不显示 @adminchen

9、优化请求参数是否必填样式,如果该参数必填,则以红色标注显示issue #22:description: "报文体", $ref: "#/definitions/MockBaseVO" 无法解析请求报文和响应报文。 @adminchen

10、fixed DELETE请求不能正确处理Query参数 issue #19:分组的支持什么时候能帮做到兼容啊 @adminchen

11、fixed 请参数类型为 formData 的参数,填写了参数值还是提示 参数不能为空issue #24:如果嵌套响应集合在此模版里不会显示 @GitHub、issue #IMMMJ:v1.8.2的 parameters 如果in参数是formData时, 字段是否填写判断有问题么? @Gitee

12、优化离线文档多行,换行、多空格显示问题

Maven坐标

<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.8.3</version>
</dependency>
Java
1
https://gitee.com/xiaoym/knife4j.git
git@gitee.com:xiaoym/knife4j.git
xiaoym
knife4j
knife4j

Search

132457 8cb2edc1 1899542 131848 70c8d3a4 1899542