关于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@EnableSwagger2WebMvcpublic 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 Configureorg.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@EnableSwagger2WebMvcpublic 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/