Knife4J在项目中的使用

Knife4j介绍

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍!

knife4j的前身是swagger-bootstrap-ui，为了契合微服务的架构发展,由于原来swagger-bootstrap-ui采用的是后端Java代码+前端Ui混合打包的方式,在微服务架构下显的很臃肿,因此项目正式更名为knife4j

---

Knife4j在项目中的使用

一、在platform-framework中引入依赖

        <dependency>
            <groupId>com.github.xiaoymingroupId>
            
            <artifactId>knife4j-spring-boot-starterartifactId>
            <version>${knife4j.version}version>
        dependency>

二、建立工具类

使用到EnableSwagger2注解，用来开启swagger和EnableKnife4j来开启knife4j

/**
 * @program:
 * @description: knife4j配置类
 * @author: cssf
 * @date: 2022-12-12
 **/
@Configuration
@EnableSwagger2
@EnableKnife4j
public class Knife4jConfiguration {

    /*需要在配置文件里配置这三个配置*/
    /*配置开启禁用swagger*/
    @Value("${swagger.enabled}")
    private boolean enabled;

    /*配置模块名*/
    @Value("${swagger.groupName}")
    private String groupName;

    /*配置需要扫描的包*/
    @Value("${swagger.basePackage}")
    private String basePackage;

    /**
     * @Description: Swagger 实例 Bean是Docket，所以通过配置Docket实例来配置Swagger
     * @return: springfox.documentation.spring.web.plugins.Docket
     * @Author: JiaChaoYang
     * @Date: 2022-09-24 - 11:36
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)//文档类型，我这里使用的是swagger3
                //是否启用swagger
                .enable(enabled)
                //包名，模块名
                .groupName(groupName)
                //删除swagger中的操作的响应体
                .useDefaultResponseMessages(false)
                //展示在Swagger页面上的自定义工程描述信息
                .apiInfo(apiInfo())
                //选择展示哪些接口
                .select()
                //配置需要扫描的路径（controller）
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                //给所有文档都生成文档路径
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * @Description: Swagger的描述信息
     * @return: springfox.documentation.service.ApiInfo
     * @Author: JiaChaoYang
     * @Date: 2022-09-24 - 11:33
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //描述信息
                .description("测试Knife4j")
                //可以通过swagger联系一个人，即联系方式
                .contact(new Contact("Chengsf", "https://127.0.0.1:8080/doc.html", "[email protected]"))
                //版本
                .version("v1.0")
                //标题
                .title("测试文档")
                .build();
    }
}

三、其他微服务模块如果需要引用，须进行如下配置

以ns-service-support-user作为实验对象

1、在controller层创建两个controller类

@Api(tags = "首页模块")
@RestController
public class IndexController {

    @ApiImplicitParam(name = "name",value = "姓名",required = true)
    @ApiOperationSupport(author = "chengsf")//author接口添加作者，order排序，接口展示顺序
    @ApiOperation(value = "向客人问好")
    @GetMapping("/sayHi")
    public ResponseEntity<String> sayHi(@RequestParam(value = "name")String name){
        return ResponseEntity.ok("Hi:"+name);
    }
}

@Api(tags = "登录模块")
@RestController
public class loginController {

    @PostMapping("login")
    @ApiOperation("登录")
    public HashMap<String, Object> login() {
        HashMap<String, Object> result = new HashMap<>(2);
        result.put("success", true);
        result.put("token", "778877669999");
        return result;
    }

}

2、引入platform-framework模块

<dependency>
    <groupId>com.normstargroupId>
    <artifactId>ns-platform-frameworkartifactId>
    <version>1.0.0-SNAPSHOTversion>
dependency>

3、在application-dev.properties增加配置，对应configuration类中的

    /*需要在配置文件里配置这三个配置*/
    /*配置开启禁用swagger*/
    @Value("${swagger.enabled}")
    private boolean enabled;

    /*配置模块名*/
    @Value("${swagger.groupName}")
    private String groupName;

    /*配置需要扫描的包*/
    @Value("${swagger.basePackage}")
    private String basePackage;

swagger.enabled=true
#登录鉴权微服务模块
swagger.groupName=support
#你的controller路径
swagger.basePackage=com.normstar.szcp.controller
#knife版本兼容问题
spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER

4、为扫到对应configuration类，添加resources/META-INF/spring.factories文件进行关联

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
  com.normstar.common.configuration.Knife4jConfiguration

或者修改启动类（将@SpringBootApplication改为@EnableAutoConfiguration，@ComponentScan(value = “com.normstar.*”)）

@Slf4j
@SpringBootApplication
@EnableDiscoveryClient
//@EnableAutoConfiguration
//@ComponentScan(value = "com.normstar.*")
public class ServiceSupportUserApplication {

    public static void main(String[] args) {
        SpringApplication.run(ServiceSupportUserApplication.class, args);
        System.out.println("支撑启动成功！");
    }
}

*4中任选一个就行

5、如果配置有拦截器或过滤器，需要进行如下配置：

需要在拦截器配置让MVC加载Swagger的静态资源

/**
    * @Description: 让MVC加载Swagger的静态资源
    * @Param: [registry]
    * @return: void
    */
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {

        registry.addResourceHandler("/**").
                addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");

        super.addResourceHandlers(registry);
    }

需要将Swagger放到白名单，即不去鉴权，需要把下边的配置给排除掉

"springfox",
"swagger",
"v3",
"webjars",
"doc.html",
"favicon.ico",
"api-docs"

6、启动之后效果

四、knife4j部分常用功能以及注解

全局参数设置：

后期各模块接口的使用，需要用到token，那么我们使用了登录接口后拿到token值，在全局参数中进行设置之后，所有的接口都会默认带上这个token值。

如果不想这么麻烦，可以使用AfterScript实现自动set token

• knife4j的增强模式提供AfterScript可以通过脚本实现将登录时token设成“环境变量”，在各个接口请求头中加入token

//ke = knife4jenvironment
var code=ke.response.data.code;
if(code=='20000'){
//获取token
var token=ke.response.data.data.token;
//设置token到请求头
ke.global.setHeader("Authorization",token);
alert("已自动设置请求头")
}

*详细可参考文档

常用部分注解：

//Swagger2注解
//主要包含注解：
@Api:定义接口分组名称
@ApiImplicitParam: 单个参数注释
@ApiImplicitParams:多个参数注释
@ApiModel:实体类定义
@ApiModelProperty:实体属性定义
@ApiOperation:接口定义
@ApiParam:参数注释
@ApiResponse:响应码
@ApiResponses:多个响应码

需要更多内容，请查阅官方文档

TFMM-1676017459819)]

*详细可参考文档

常用部分注解：

//Swagger2注解
//主要包含注解：
@Api:定义接口分组名称
@ApiImplicitParam: 单个参数注释
@ApiImplicitParams:多个参数注释
@ApiModel:实体类定义
@ApiModelProperty:实体属性定义
@ApiOperation:接口定义
@ApiParam:参数注释
@ApiResponse:响应码
@ApiResponses:多个响应码

需要更多内容，请查阅官方文档

https://doc.xiaominfo.com/docs/quick-start

感谢下面这位兄弟，能够耐心解答！

https://blog.csdn.net/lovexinxin_/article/details/127150672#comments_24576986