springboot+knife4j集成及禁用调试功能

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包中,并且后续也会满足开发者更多的个性化需求.

快速开始

本次示例使用Spring Boot作为脚手架来快速集成Knife4j,Spring Boot版本2.4.0.RELEASE,Knife4j版本2.0.8，完整代码可以去参考knife4j-spring-boot-fast-demo

第一步：在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.nucarf.config;


import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver;
import org.springframework.beans.factory.annotation.Autowired;
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.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        String groupName="用户管理";
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .host("https://www.baidu.com")
                .apiInfo(apiInfo())
                .groupName(groupName)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.nucarf.controller"))
                .paths(PathSelectors.any())
                .build();
              
        return docket;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger-bootstrap-ui RESTful APIs")
                .description("swagger-bootstrap-ui")
                .termsOfServiceUrl("http://www.nucarf.com")
                .contact("nucarf@mail.com")
                .version("9.9")
                .build();
}

yml配置

server:
  port: 8081

#knife4j增强 ，填写了knife4j:
#					enable: true
#即可不写@EnableKnife4j注解
knife4j:
  enable: true
  #调试功能是否开启
  setting:
    enableDebug: true

controller层

package com.nucarf.controller;


import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Api(tags = "用户管理")
public class UserController {
    @GetMapping("/test")
    @ApiOperation(value = "用户ID返回")
    @ApiImplicitParam(name = "userId",value = "ID",required = true,paramType = "Integer")
    public String test(@RequestParam("userId") Integer userId){
        return "hello swagger"+userId;
    }
}

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

界面效果图如下：

自Knife4j版本2.0.8后，禁用调试功能得到简化

yml配置:

knife4j:
  enable: true
  setting:
    enableDebug: false

属性说明：

• enableDebug:该属性是一个Boolean值，代表是否启用调试功能,默认值为true(代表开启调试)，如果要禁用调试，该值设为false

开发者配置好后,最核心的一步，也是最后最重要的一步，开发者需要在创建Docket逻辑分组对象时，通过Knife4j提供的工具对象OpenApiExtensionResolver将扩展属性进行赋值

配置类代码如下：

package com.nucarf.config;


import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver;
import org.springframework.beans.factory.annotation.Autowired;
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.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {
    private final OpenApiExtensionResolver openApiExtensionResolver;

    @Autowired
    public Knife4jConfiguration(OpenApiExtensionResolver openApiExtensionResolver) {
        this.openApiExtensionResolver = openApiExtensionResolver;
    }
    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        String groupName="用户管理";
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .host("http://www.nucarf.com")
                .apiInfo(apiInfo())
                .groupName(groupName)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.nucarf.controller"))
                .paths(PathSelectors.any())
                .build()
                .extensions(openApiExtensionResolver.buildSettingExtensions());
        return docket;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("knife4j接口文档")
                .description("knife4j接口文档")
                .termsOfServiceUrl("http://www.nucarf.com")
                .contact("nucarf@mail.com")
                .version("9.9")
                .build();
    }
}

通过上面示例代码，主要步骤如下：

1、通过@Autowired注解引入Knife4j向Spring容器注入的Bean对象OpenApiExtensionResolver

2、最终在Dcoket对象构建后，通过调用Docket对象的extensions方法进行插件赋值

3、插件赋值需要调用OpenApiExtensionResolver提供的buildSettingExtensions方法，获取x-settings的增强属性

最终界面效果如下：

e4j向Spring容器注入的Bean对象OpenApiExtensionResolver`

2、最终在Dcoket对象构建后，通过调用Docket对象的extensions方法进行插件赋值

3、插件赋值需要调用OpenApiExtensionResolver提供的buildSettingExtensions方法，获取x-settings的增强属性

最终界面效果如下：