从零搭建开发脚手架 迎合国人需求，Knife4j替换swagger_knife4j 转 swagger

Knife4j简介

官网地址：https://doc.xiaominfo.com/

功能特性：

• 基于左右菜单式的布局方式,是更符合国人的操作习惯吧.文档更清晰
• 个性化配置项,支持接口地址、接口description属性、UI增强等个性化配置功能
• 接口排序、Swagger资源保护、导出Markdown、参数缓存众多强大功能

Knife4j的前身是swagger-bootstrap-ui,前身swagger-bootstrap-ui是一个纯swagger-ui的ui皮肤项目。

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

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

Knife4j本身已经引入了springfox，开发者在使用时不用再单独引入Springfox的具体版本，否额会导致版本冲突。

快速开始

版本说明

在更名为Knife4j之前,原来的名称是叫swagger-bootstrap-ui，这是两种不一样风格的Ui,对比情况如下：

Knife4j从开源至今,目前主要经历版本的变化，分别如下：

需要注意的是，目前Knife4j的主版本依然是沿用2.x的版本号，也就是从2.0.6版本开始逐步升级，迭代发布时版本会随之升级，但同时3.x版本也会同步更新发布，主要是满足开发者对于springfox3以及OpenAPI3规范的使用

解读：目前选2.0.6~就完事了。使用Knife4j2.0.6及以上的版本，Spring Boot的版本必须大于等于2.2.x

依赖导入

在maven项目的pom.xml中引入Knife4j的依赖包，代码如下：

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

当前时间 2021-04-08 最新版本 2.0.8

配置依赖

创建Swagger配置依赖，代码如下：

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        //.title("swagger-bootstrap-ui-demo RESTful APIs")
                        .description("# swagger-bootstrap-ui-demo RESTful APIs")
                        .termsOfServiceUrl("http://www.xx.com/")
                        .contact("xx@qq.com")
                        .version("1.0")
                        .build())
                //分组名称
                .groupName("2.X版本")
                .select()
                //这里指定Controller扫描包路径
                //.apis(RequestHandlerSelectors.basePackage("com.github.xiaoymin.knife4j.controller"))
                            // 扫描所有有注解的api，用这种方式更灵活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

接口配置

@Api(tags = "首页模块")
@RestController
public class IndexController {

    @ApiImplicitParam(name = "name",value = "姓名",required = true)
    @ApiOperation(value = "向客人问好")
    @GetMapping("/sayHi")
    public ResponseEntity<String> sayHi(@RequestParam(value = "name")String name){
        return ResponseEntity.ok("Hi:"+name);
    }
}
1
2
3
4
5
6
7
8
9
10
11

浏览器验证

此时，启动Spring Boot工程，在浏览器中访问：http://localhost:port/doc.html

界面效果图如下：

实战经验

接口描述

@RestController(value = "/user")
@Api( tags = "用户管理") // 这里是分组名称
public class UserController {

    @ApiOperation(value = "获取所有的用户")// 具体接口描述
    @GetMapping
    public List<String> getUsers() {
        return Arrays.asList("user1", "user2");
    }
}
1
2
3
4
5
6
7
8
9
10

• 类@Api( tags = "用户管理")，用于接口分组说明
• 方法@ApiOperation(value = "获取所有的用户")，用于具体接口描述

隐藏部分接口

• 1.使用@ApiIgnore

@ApiIgnore
@ApiOperation(value = "This method is used to get the author name.")
@GetMapping("/getAuthor")
public String getAuthor() {
    return "Umang Budhwar";
}
1
2
3
4
5
6

• 2.使用@ApiOperation

@ApiOperation(value = "This method is used to get the current date.", hidden = true)
@GetMapping("/getDate")
public LocalDate getDate() {
    return LocalDate.now();
}
1
2
3
4
5

生产中关闭Swagger

第一步：使用@Profile注解，SpEL表达式不是prod的环境生效

@Configuration 
@Profile({"!prod"})
@EnableSwagger2 
public class SwaggerConfig {
}
1
2
3
4
5

第二步：通过使用spring.profiles.active属性的不同设置启动我们的应用程序

VM参数：

  -Dspring.profiles.active=prod // Swagger is disabled

  -Dspring.profiles.active=prod,anyOther // Swagger is disabled

  -Dspring.profiles.active=swagger // Swagger is enabled

  -Dspring.profiles.active=swagger,anyOtherNotProd // Swagger is enabled

  none // Swagger is disabled
1
2
3
4
5
6
7
8
9

或者在application.yaml中设置不同的环境。

实体属性注释

@ApiModelProperty(
  value = "first name of the user",
  name = "firstName",
  dataType = "String",
  example = "Vatsal")
String firstName;
1
2
3
4
5
6

注意：Controller返回时

请求参数注释

    @GetMapping("/xxxx")
    @ApiOperation(value = "xxx-xxx ", tags = ApiConstants.CAMERA_VIDEO)
    public Response xxxx(@ApiParam(value = "xxxid", required = true) @RequestParam Long id,
                                   @ApiParam(value = "xxx", required = true) @RequestParam String xxx,
                                   @ApiParam(value = "xxcode") @RequestParam(required = false) String xxx,
                                   @ApiParam(value = "xxxx）", required = true) @RequestParam Integer xxx) {
1
2
3
4
5
6
7

访问权限控制

配置此属性后,所有资源都会屏蔽输出.

knife4j:
  # 开启增强配置 
  enable: true
　# 开启生产环境屏蔽
  production: true
1
2
3
4
5

访问增加用户名密码

knife4j:
  # 开启增强配置 
  enable: true
　# 开启Swagger的Basic认证功能,默认是false
  basic:
      enable: true
      # Basic认证用户名
      username: test
      # Basic认证密码
      password: 123
1
2
3
4
5
6
7
8
9
10

如果用户开启了basic认证功能,但是并未配置用户名及密码,Knife4j提供了默认的用户名和密码：admin/123321

接口排序

第一步：打开增强模式

knife4j:
  enable: true
1
2

第二步：使用Knife4j提供的增强注解@ApiOperationSupport中的order字段

@ApiOperationSupport(order = 33)
@ApiOperation(value = "忽略参数值-Form类型")
@PostMapping("/ex")
public Rest<LongUser> findAll(LongUser longUser) {
    Rest<LongUser> r=new Rest<>();
    r.setData(longUser);
    return r;
}
1
2
3
4
5
6
7
8

分组排序

前提打开增强模式

Controller之间的排序主要有两种方式,排序的规则是倒序,但是排序的最小值必须大于0

建议优先级是：@ApiSupport>@ApiSort>@Api

对于最高级别的值,可以从999开始

@ApiSupport注解自2.0.3版本引入

第一种,使用@ApiSupport注解中的属性order,代码示例如下：

@Api(tags = "2.0.3版本-20200312")
@ApiSupport(order = 284)
@RestController
@RequestMapping("/api/nxew203")
public class Api203Constroller {      
}
1
2
3
4
5
6

第二种情况,使用knife4j提供的增强注解@ApiSort,代码示例如下：

@Api(tags = "2.0.2版本-20200226")
@ApiSort(286)
@RestController
@RequestMapping("/api/nxew202")
public class Api202Controller {     
}
1
2
3
4
5
6

第三种,使用注解@Api中的属性position(需要注意的是该属性以及过时,建议开发者使用第一种),代码示例如下：

@Api(tags = "2.0.2版本-20200226",position = 286)
@RestController
@RequestMapping("/api/nxew202")
public class Api202Controller {    
}
1
2
3
4
5

模拟Postman

开启动态参数请求：

可以自定义请求头，请求类型，请求参数：

微服务网关聚合API

Cloud(云端)模式和Disk模式大同小异，主要的区别是获取OpenAPI规范的方式换成了基于HTTP接口而已

完整代码请参考knife4j-aggregation-cloud-demo(opens new window)

本次Cloud聚合以Knife4j目前部署的线上demo为例，本地聚合在线的OpenAPI，并且可以本地调试，Knife4jAggregation组件会自动帮助我们转发

任意取目前Knife4j的线上demo两个OpenAPI规范接口地址：

• http://knife4j.xiaominfo.com/v2/api-docs?group=2.X版本(opens new window)
• http://knife4j.xiaominfo.com/v2/api-docs?group=3.默认接口(opens new window)

主要步骤如下：

1、创建Spring Boot项目，引入Knife4jAggregation的依赖包，完整pom文件如下：

     <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-aggregation-spring-boot-starter</artifactId>
            <version>2.0.8</version>
        </dependency>
1
2
3
4
5

2、配置文件如下

server:
  port: 19081
knife4j:
  enableAggregation: true
  cloud:
    enable: true
    routes:
      - name: 测试分组1
        uri: knife4j.xiaominfo.com
        location: /v2/api-docs?group=2.X版本
        servicePath: /laker
      - name: 测试分组2
        uri: knife4j.xiaominfo.com
        location: /v2/api-docs?group=3.默认接口
1
2
3
4
5
6
7
8
9
10
11
12
13
14

• knife4j.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是通过uri+location的组合路径进行访问
• 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密码

3、启动项目，访问doc.html进行查看，效果图如下：

---

加群一起抱团取暖，共同进步