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

lakernote
644 阅读6分钟

文章目录

Knife4j简介

官网地址：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,对比情况如下：

软件开发语言&框架状态最后版本风格
Knife4jJava、JavaScript、Vue持续更新中无黑色
swagger-bootstrap-uiJava、JavaScript、jQuery停更1.9.6蓝色

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

版本说明
1.9.6蓝色皮肤风格,开始更名，增加更多后端模块
2.0~2.0.5Ui重写，底层依赖的springfox框架版本是2.9.2
2.0.6~底层springfox框架版本升级知2.10.5,OpenAPI规范是v2
3.0~底层依赖springfox框架版本升级至3.0.3,OpenAPI规范是v3

需要注意的是，目前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>

当前时间 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;
    }
}

接口配置

@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);
    }
}

浏览器验证

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

界面效果图如下：

img

实战经验

接口描述

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

    @ApiOperation(value = "获取所有的用户")// 具体接口描述
    @GetMapping
    public List<String> getUsers() {
        return Arrays.asList("user1", "user2");
    }
}
  • 类@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";
}
  • 2.使用@ApiOperation
@ApiOperation(value = "This method is used to get the current date.", hidden = true)
@GetMapping("/getDate")
public LocalDate getDate() {
    return LocalDate.now();
}

生产中关闭Swagger

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

@Configuration 
@Profile({"!prod"})
@EnableSwagger2 
public class SwaggerConfig {
}

第二步：通过使用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

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

实体属性注释

@ApiModelProperty(
  value = "first name of the user",
  name = "firstName",
  dataType = "String",
  example = "Vatsal")
String firstName;

请求参数注释


    @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) {

访问权限控制

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

knife4j:
  # 开启增强配置 
  enable: true
　# 开启生产环境屏蔽
  production: true

访问增加用户名密码

knife4j:
  # 开启增强配置 
  enable: true
　# 开启Swagger的Basic认证功能,默认是false
  basic:
      enable: true
      # Basic认证用户名
      username: test
      # Basic认证密码
      password: 123

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

接口排序

第一步：打开增强模式

knife4j:
  enable: true

第二步：使用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;
}

分组排序

前提打开增强模式

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 {      
}

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

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

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

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

模拟Postman

开启动态参数请求：

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

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

🍎QQ群【837324215】
🍎关注我的公众号【Java大厂面试官】，一起学习呗🍎🍎🍎
🍎个人vx【lakernote】

img

avatar
文章
阅读
粉丝