# # [v2.0.6-2020/10/26 Knife4j 2.0.6发布,支持OpenAPI3及Auth2认证]

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

关键词：OpenAPI3、Auth2.0、AfterScript、Springfox3.0、增强改善

文档：https://doc.xiaominfo.com
(opens new window)

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

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

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

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

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

## # 特性 & 优化

2.0.6是继续在上个版本中进行迭代更新,开发者使用OpenAPI2的结构可以直接修改版本号即可进行升级,springfox框架升级到`2.10.5`

> springfox 2.10.5 版本变化：

> 1、spring-plugin组件升级到2.0.0，移除了guava包

> 2、@EnableSwagger2注解升级为@EnableSwagger2WebMvc

Maven引用：

    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-spring-boot-starter</artifactId>
        <!--OpenAPI2.0的开发者继续使用Knife4j 2.x系列的版本-->
        <version>2.0.6</version>
    </dependency>

1、OAuth2认证功能的支持:简化模式(implicit)、授权码模式(authorization_code)、密码模式(password)、客户端模式(client_credentials),详细规则请参考文档
(opens new window)

2、针对`@RequestBody`注解标注的请求实体类，在接口请求参数时是否必须(`require`)的显示异常的问题Gitee #I1VBGB
(opens new window)、Gitee #I1YK2Q
(opens new window)、Gitee #I1WCMF
(opens new window)、Gitee #I1VDSH
(opens new window)、GitHub #277
(opens new window)

3、针对服务端指定`consumes`的情况优化，如果服务端不指定,Ui会默认根据参数类型进行适配Gitee #I1VE25
(opens new window)

4、解决在创建`Docket`对象时赋予`Host`属性后,文档界面显示接口地址异常的问题Gitee #I1XYG9
(opens new window)

5、微服务网关聚合文档时,自定义分组名称导致增强失败的问题Gitee #I1Y79W
(opens new window)

6、针对`query`类型的参数，如果该参数是schema类型,解析该schema为json提作为请求值.Gitee #I1VLHH
(opens new window),如下图：

- 文档展示：

- 调试效果：

7、调试栏新增`AfterScript`特性,开发者可根据`Knife4j`定义的全局变量编写自定义`JavaScript`脚本,增强接口交互体验Gitee #I1YNU3
(opens new window)、Gitee #I1CAAD
(opens new window),关于`AfterScript`特性可参考文档
(opens new window)

主要应用场景：

- 针对JWT类型的接口,调用登录接口后,每个接口请求时带上Token参数,此时可以通过该脚本动态赋值全局token参数,省去复制粘贴的麻烦.

假设某一个登录接口响应的JSON内容如下：

    {
      "code": 8200,
      "message": null,
      "data": {
        "token": "1y1tn8tvw93fxixp79dcx0nugixkw4su"
      }
    }

该接口是登录接口,除该接口外其余接口请求都需要带上`token`的请求头,因此我们访问登录接口后,设置全局Header参数`token`,此操作`Knife4j`接下来会为每一个请求接口带上`token`参数，代码如下：

    var code=response.data.code;
    if(code==8200){
        //判断,如果服务端响应code是8200才执行操作
        //获取token
        var token=response.data.data.token;
        //1、如何参数是Header，则设置全局Header
        ke.global.setHeader("token",token);
    }

8、通过创建Docket对象时设置`globalOperationParameters`全局参数时,针对`header`类型的`allowableValues`不支持下拉框选择的问题Gitee #I1OC0H
(opens new window)

代码如下：

    parameters.add(new ParameterBuilder().name("header-test").description("balabala")
                    .modelRef(new ModelRef("string"))
                    .parameterType("header")
                    .allowableValues(new AllowableListValues(Arrays.asList("下拉1", "下拉2"), "string"))
                    .required(false).order(1).build());
    new Docket(DocumentationType.SWAGGER_2)
                    .host("https://www.baidu.com")
                    .apiInfo(apiInfo())
                    .groupName("2.X版本")
                    .globalOperationParameters(parameters)

最终效果：

9、离线导出功能板块增加导出OpenAPI的原始JSON格式数据，导出该逻辑分组下所有接口的OpenAPI原始json格式。如下图：

10、针对单个接口，提供OpenAPI的源码格式，可以通过复制或者下载该源码格式直接导入POSTMAN进行测试Gitee #I1Z7AP
(opens new window)。如下图：

11、增强注解`@EnableKnfie4j`增加Spring Boot中的Conditional条件`@ConditionalOnWebApplication`,仅在Web环境下加载，避免在使用`junit`单元测试时出现异常。

12、增强模式的改进,主要有两个变化,更加详细的使用规则，开发者请参考文档
(opens new window)：

- 提供`spring.factories`进行自动装置,开发者可以直接在Spring Boot的配置文件`yml`或者`property`等使用属性`knife4j.enable:true`进行开启使用，配置属性后无需再使用`@EnableKnife4j`注解

- 提供`spring-configuration.meta.json`文件，对`Knife4j`提供的各个增强配置属性进行注释，方便开发者在配置文件中进行配置，如下图：

13、针对其它文档的配置，开发者可以根据每一个逻辑分组Docket进行配置，其他文档支持自定义文档的分组标题

14、接口排序需求无需再Ui界面勾选增强，只需要在配置文件中开启`knife4j.enable=true`接口，然后使用`@ApiSupport`注解或者`@ApiSort`在`Controller`类上进行使用，优先级`@ApiSupport>@ApiSort`,该方式更加融合了springfox框架的特性，也更符合对扩展属性扩展的规范，在OpenAPI结构节点增加`x-order`扩展参数，如下图：

15、移除增强扩展接口地址`/v2/api-docs-ext`,个性化配置及增强通过后端配置文件进行配置即可,通过更加规范的使用增强注解,符合OpenAPI的扩展属性规范。

16、其他文档以更加符合OpenAPI的扩展规范进行展示，开发者可以在yml配置文件中配置多个分组文档(`前提是knife4j.enable=true`),然后再创建的`Docket`对象中使用`Knife4j`提供的`OpenApiExtensionResolver`扩展`extension`,最终配置的md文件会在文档中进行分组呈现.GitHub #115
(opens new window)

`application.yml`配置示例代码如下：

    knife4j:
      enable: true
      documents:
        -
          group: 2.X版本
          name: 接口签名
          locations: classpath:sign/*
        -
          group: 2.X版本
          name: 另外文档分组请看这里
          locations: classpath:markdown/*

Java代码：

    @Configuration
    @EnableSwagger2WebMvc
    @Import(BeanValidatorPluginsConfiguration.class)
    public class SwaggerConfiguration {

       private final OpenApiExtensionResolver openApiExtensionResolver;

        @Autowired
        public SwaggerConfiguration(OpenApiExtensionResolver openApiExtensionResolver) {
            this.openApiExtensionResolver = openApiExtensionResolver;
        }

        @Bean(value = "defaultApi2")
        public Docket defaultApi2() {
            String groupName="2.X版本";
            Docket docket=new Docket(DocumentationType.SWAGGER_2)
                    .host("https://www.baidu.com")
                    .apiInfo(apiInfo())
                    .groupName(groupName)
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.swagger.bootstrap.ui.demo.new2"))
                    //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                    .paths(PathSelectors.any())
                    .build()
                //此处调用openApiExtensionResolver的方法获取extensions集合
                    .extensions(openApiExtensionResolver.buildExtensions(groupName))
                    .securityContexts(CollectionUtil.newArrayList(securityContext())).securitySchemes(CollectionUtil.newArrayList(apiKey()));
            return docket;
        }
    }

最终Ui界面效果图：

17、针对使用`@ApiModelProperty`注解，给予实体String类型的属性字段赋值`example`示例值json字符串时显示异常的问题GitHub #233
(opens new window)

18、请求示例和响应示例中的长整形精度丢失的问题GitHub #269
(opens new window)

19、针对当前接口存在Authorze认证情况下，没有点击该功能时参数不会默认在接口调试中的Bug以及query类型参数始终出现在请求头参数栏的情况Gitee #I1VC4I
(opens new window)

20、去除Ui界面中个性化设置中的启用增强配置。

21、增强注解`@ApiOperationSupport`与`@DynamicResponseParameters`同时使用时,动态响应字段丢失的问题Gitee #I22K0R
(opens new window)

22、离线文档下载失败的问题，变量引用错误导致Gitee #I1W5UB
(opens new window)

## # OpenAPI3

如果开发者想使用springfox的OpenAPI3的版本,Knife4j此次发布了两个版本,针对3.0版本,Knife4j底层升级springfox组件到`springfox3.0.0`,并且版本号从`3.x`系列开始,代表OpenAPI3,以区分`2.x`系列。

Maven引用

    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-spring-boot-starter</artifactId>
        <!--如果想使用springfox3.0及OpenAPI3请用3.x版本-->
        <version>3.0</version>
    </dependency>

针对SpringFox3.0的版本,作者在开发过程中虽然在Ui上对OpenAPI3进行了支持,但是目前springfox3.0还存在诸多的问题，建议开发者慎重使用springfox3。不管是对于OpenApi2以及OpenApi3的支持，目前springfox3在兼容性等方面都存在一些问题,毕竟刚发布一个版本.

相对而言,springfox2.x系列的版本较稳定.当Springfox对于3.0的结构相对稳定后,Knife4j的主分支版本会向3.0靠拢。

相关ISSUES:

- #I1UGH7 swagger 2.9.2 对 javax.validation 支持缺少，可考虑升级到 2.10.5
  (opens new window)
- #I1R9J1 关于支持 Springfox Swagger 3.0.0
  (opens new window)
- #I1VYDM 早日支持下springfox-boot-starter 3.0
  (opens new window)
- #I1X27Y swagger 升级到3.0后的兼容问题
  (opens new window)
- #I1QQYH knife4j-vue-v3 setInstanceBasicPorperties 方法中逻辑问题
  (opens new window)
- #275 springfox-3.0.0与knife4j-2.0.5冲突？
  (opens new window)
- #268 spring boot 2.3.3、springfox 3.0.0与knife4j2.0.4集成报错问题
  (opens new window)
- #265 spring-plugin-core的兼容问题
  (opens new window)

## # 特点

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

## # 界面

接口文档显示界面如下：

接口调试界面如下：

Swagger Models功能

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

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

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

界面效果如下图：

## # Star & Issue

感谢各位朋友的支持,前往https://gitee.com/xiaoym/knife4j
(opens new window)点个Star吧~~ ：）

被围观 人次