关于springboot:笑小枫的SpringBoot系列二基于swagger2的knife4j接口文档

2 配置后端接口

2.1 什么是 knife4j😴

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 前端.

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

次要的变动是, 我的项目的相干类包门路更换为 com.github.xiaoymin.knife4j 前缀, 开发者应用加强注解时须要替换包门路

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

knife4j沿用 swagger-bootstrap-ui 的版本号, 第 1 个版本从 1.9.6 开始, 对于应用办法, 请参考文档。

2.2 怎么应用 knife4j

👉第一步：在 maven 我的项目的 pom.xml 中引入 Knife4j 的依赖包，代码如下：👇

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

👉第二步：创立 Swagger 配置依赖，代码如下：👇

package com.maple.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

/**
 * @author 笑小枫
 * @date 2022/6/28
 */
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {@Bean(value = "example")
    public Docket example() {return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("笑小枫实例演示接口")
                        .description("笑小枫实例演示接口")
                        .termsOfServiceUrl("http://127.0.0.1:6666")
                        .contact(new Contact("笑小枫", "https://www.xiaoxiaofeng.site", "zfzjava@163.com"))
                        .version("1.0")
                        .build())
                // 分组名称
                .groupName("演示实例接口")
                .select()
                // 这里指定 Controller 扫描包门路
                .apis(RequestHandlerSelectors.basePackage("com.maple.demo.controller"))
                .paths(PathSelectors.any())
                .build();}
}

👉第三步：创立一个 Controller👇

package com.maple.demo.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiModelProperty;
import io.swagger.annotations.ApiOperation;
import lombok.Data;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author zhangfuzeng
 * @date 2022/6/30
 */
@Api(tags = "实例演示 -Knife4j 接口文档")
@RestController
@RequestMapping("/example")
public class TestKnife4jController {@ApiOperation(value = "Knife4j 接口文档演示")
    @GetMapping("/testKnife4j")
    public Test testKnife4j(Test param) {Test test = new Test();
        test.setName("笑小枫");
        test.setAge(18);
        test.setRemark("大家好，我是笑小枫，喜爱我的小伙伴点个赞呗，欢送拜访我的集体博客：http://www.xiaoxiaofeng.site");
        return test;
    }

    @Data
    static class Test {@ApiModelProperty(value = "姓名")
        private String name;

        @ApiModelProperty(value = "年龄")
        private Integer age;

        @ApiModelProperty(value = "形容")
        private String remark;
    }
}

2.3 看下页面成果👌

我的项目启动后，在浏览器输出 http://127.0.0.1:6666/doc.html 拜访

接口调试：

2.4 加强模式😦

Knife4j 自 2.0.6 版本开始, 将目前在 Ui 界面中一些个性化配置剥离, 开发者能够在后端进行配置，并且提供的 knife4j-spring-boot-strater 组件主动装载

spring.factories 配置如下：

# Auto Configure
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.github.xiaoymin.knife4j.spring.configuration.Knife4jAutoConfiguration

在 Spring Boot 配置文件中, 残缺的配置如下:

knife4j:
  enable: true
  documents:
    -
      group: 2.X 版本
      name: 接口签名
      locations: classpath:sign/*
  setting:
    language: zh-CN
    enableSwaggerModels: true
    enableDocumentManage: true
    swaggerModelName: 实体类列表
    enableVersion: false
    enableReloadCacheParameter: false
    enableAfterScript: true
    enableFilterMultipartApiMethodType: POST
    enableFilterMultipartApis: false
    enableRequestCache: true
    enableHost: false
    enableHostText: 192.168.0.193:8000
    enableHomeCustom: true
    homeCustomLocation: classpath:markdown/home.md
    enableSearch: false
    enableFooter: false
    enableFooterCustom: true
    footerCustomContent: Copyright  2022-[笑小枫](https://www.xiaoxiaofeng.site)
    enableDynamicParameter: false
    enableDebug: true
    enableOpenApi: false
    enableGroup: true
  cors: false
  production: false
  basic:
    enable: false
    username: test
    password: 123123

在以前的版本中, 开发者须要在配置文件中手动应用 @EnableKnife4j 来应用加强，自 2.0.6 版本后, 只须要在配置文件中配置 knife4j.enable=true 即可不在应用注解

留神：要应用 Knife4j 提供的加强，knife4j.enable=true必须开启

各个配置属性阐明如下：

对于个性化文档 (knife4j.documents) 以及个性化设置 (knife4j.setting), 有一些轻微的区别, 开发者在配置文件中进行配合好后, 还须要在创立 Docket 对象时调用Knife4j 提供的扩大 Extesions 进行赋值

示例代码如下：

package com.maple.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

/**
 * @author 笑小枫
 * @date 2022/6/28
 */
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {
    /* 引入 Knife4j 提供的扩大类 */
    private final OpenApiExtensionResolver openApiExtensionResolver;

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

    @Bean(value = "example")
    public Docket example() {
        String groupName="演示实例接口";
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("笑小枫实例演示接口")
                        .description("笑小枫实例演示接口")
                        .termsOfServiceUrl("http://127.0.0.1:6666")
                        .contact(new Contact("笑小枫", "http://www.xiaoxiaofeng.site", "zfzjava@163.com"))
                        .version("1.0")
                        .build())
                // 分组名称
                .groupName(groupName)
                .select()
                // 这里指定 Controller 扫描包门路
                .apis(RequestHandlerSelectors.basePackage("com.maple.demo.controller"))
                .paths(PathSelectors.any())
                .build()
                // 赋予插件体系
                .extensions(openApiExtensionResolver.buildExtensions(groupName));
    }
}

buildExtensions办法须要传入分组名称, 该分组名称次要是为了辨别开发者在构建自定义文档时，在不同的 Docket 逻辑分组下进行区别显示。

OpenApiExtensionResolver辅助类须要配置 knife4j.enable=true 能力主动@Autowired

加强成果开启后, 在最终调用接口时，Knife4j 会增加扩大属性x-openapi, 如下图：

更多功能，请参考官网文档：https://doc.xiaominfo.com/knife4j/