【笑小枫的SpringBoot系列】【二】基于swagger2的knife4j接口文档

头像
笑小枫
     上海
    阅读 9 分钟
    1
    头图

    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访问

    image-20220711165333302

    接口调试：

    image-20220711165425505

    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.enablefalse是否开启Knife4j增强模式
    knife4j.corsfalse是否开启一个默认的跨域配置,该功能配合自定义Host使用
    knife4j.productionfalse是否开启生产环境保护策略,详情参考文档
    knife4j.basic 对Knife4j提供的资源提供BasicHttp校验,保护文档
    knife4j.basic.enablefalse关闭BasicHttp功能
    knife4j.basic.username basic用户名
    knife4j.basic.password basic密码
    knife4j.documents 自定义文档集合，该属性是数组
    knife4j.documents.group 所属分组
    knife4j.documents.name 类似于接口中的tag,对于自定义文档的分组
    knife4j.documents.locations markdown文件路径,可以是一个文件夹(classpath:markdowns/*)，也可以是单个文件(classpath:md/sign.md)
    knife4j.setting 前端Ui的个性化配置属性
    knife4j.setting.enableAfterScripttrue调试Tab是否显示AfterScript功能,默认开启
    knife4j.setting.languagezh-CNUi默认显示语言,目前主要有两种:中文(zh-CN)、英文(en-US)
    knife4j.setting.enableSwaggerModelstrue是否显示界面中SwaggerModel功能
    knife4j.setting.swaggerModelNameSwagger Models重命名SwaggerModel名称,默认
    knife4j.setting.enableDocumentManagetrue是否显示界面中"文档管理"功能
    knife4j.setting.enableReloadCacheParameterfalse是否在每个Debug调试栏后显示刷新变量按钮,默认不显示
    knife4j.setting.enableVersionfalse是否开启界面中对某接口的版本控制,如果开启，后端变化后Ui界面会存在小蓝点
    knife4j.setting.enableRequestCachetrue是否开启请求参数缓存
    knife4j.setting.enableFilterMultipartApisfalse针对RequestMapping的接口请求类型,在不指定参数类型的情况下,如果不过滤,默认会显示7个类型的接口地址参数,如果开启此配置,默认展示一个Post类型的接口地址
    knife4j.setting.enableFilterMultipartApiMethodTypePOST具体接口的过滤类型
    knife4j.setting.enableHostfalse是否启用Host
    knife4j.setting.enableHomeCustomfalse是否开启自定义主页内容
    knife4j.setting.homeCustomLocation 主页内容Markdown文件路径
    knife4j.setting.enableSearchfalse是否禁用Ui界面中的搜索框
    knife4j.setting.enableFootertrue是否显示Footer
    knife4j.setting.enableFooterCustomfalse是否开启自定义Footer
    knife4j.setting.footerCustomContentfalse自定义Footer内容
    knife4j.setting.enableDynamicParameterfalse是否开启动态参数调试功能
    knife4j.setting.enableDebugtrue启用调试
    knife4j.setting.enableOpenApitrue显示OpenAPI规范
    knife4j.setting.enableGrouptrue显示服务分组

    关于个性化文档(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,如下图：

    image-20220630132424363

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

    springbootjavaspring
    笑小枫
    4 声望3 粉丝
    « 上一篇
    【笑小枫的SpringBoot系列】【一】SpringBoot项目创建
    下一篇 »
    【笑小枫的SpringBoot系列】【三】SpringBoot集成Mybatis Plus

    引用和评论

    推荐阅读
    头像
    Java分布式环境下并发编程实践

    笑小枫阅读 1.3k

    头像
    Java8的新特性

    codecraft赞 35阅读 31.4k评论 1

    头像
    Java11的新特性

    codecraft赞 28阅读 22.2k评论 3

    头像
    Java5的新特性

    codecraft赞 13阅读 25.9k

    头像
    Java9的新特性

    codecraft赞 20阅读 18.4k

    头像
    Java13的新特性

    codecraft赞 17阅读 13.5k

    头像
    Java7的新特性

    codecraft赞 10阅读 21.1k

    0 条评论
    得票最新