三.前后端分离，spring boot 集成 Knife4j 2.0.7 实现API 文档

最新推荐文章于 2024-05-21 17:29:37 发布

路灯下的程序员

最新推荐文章于 2024-05-21 17:29:37 发布

阅读量1.1k

点赞数

文章标签： spring boot java swagger2

本文链接：https://blog.csdn.net/m0_64684588/article/details/121809930

版权

本文是在二. spring boot访问数据库，实现增删查改_m0_64684588的博客-CSDN博客上进行更新

Knife4j 官网：knife4j

引入需要的依赖（只需要引入 knife4j 就可以了）

目前已经发行的Knife4j版本，Knife4j本身已经引入了springfox，开发者在使用时不用再单独引入Springfox的具体版本，否额会导致版本冲突。

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

注：knife4j 最的2.0.7 还不支持spring boot 2.6.1 版本，所以只能先将sping boot 的版本退回到2.5.7就可以了。

1.简单使用

在config 目录创建 Knife4jConfiguration 配置类

package com.ldxdcxy.demo.config.Knife4j;

import java.util.ArrayList;

import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver;
import lombok.RequiredArgsConstructor;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;


/**
 * Knife4j 配置
 * @author ldxdcxy
 */
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

 /**
     * 分组名称
     */
    private String groupName="ldxdcxy";


    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 配置api文档的分组
                .groupName(groupName)
                .select()
                //配置扫描路径
                .apis(RequestHandlerSelectors.basePackage("com.ldxdcxy.demo"))
                // 配置过滤哪些
                .paths(PathSelectors.any())
                .build();
    }
    /**
     * api基本信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfo("spring boot swagger-ui 文档",
                "spring boot swagger 测试",
                "v1.0",
                "https://doc.xiaominfo.com/",
                //作者信息
                new Contact("路灯下的程序猿", "https://mp.csdn.net/mp_blog/creation/editor/121809930", "xxxxx@qq.com"),
                "Apache 2.0",
                "https://mp.csdn.net/mp_blog/creation/editor/121809930",
                new ArrayList());
    }
}

访问方式：

http://{ip}:{port}/doc.html 对应 http://127.0.0.1:8081/doc.html

效果：

从效果而言，还是比较喜好版本为：1.9.6 的蓝色背景的样式

官网版本介绍

版本1.9.6已停止更新了

如果有小伙伴不使用增强功能,纯粹换一个swagger的前端皮肤，可以将 knife4j 版本退回到1.9.6

版本1.9.6 ：通过@EnableSwagger2 开启配置

本文版本2.0.7 ：通过 @EnableSwagger2WebMvc 开启设置

2.项目常用注解使用

控制层controller

类:@Api(tags="用户前端控制器") 需要隐藏: @Api(tags = "用户前端控制器",hidden = true)

方法:1@ApiOperation(value = "添加用户信息",notes = "添加用户信息",response = Integer.class)
2@ApiImplicitParams({ @ApiImplicitParam(name = "userId", value = "用户ID", required = true), @ApiImplicitParam(name = "serverId", value = "业务ID", required = true) })

路径参数 /{id}: @ApiImplicitParam(name="id",value="查询ID",required=true)

普通参数: @ApiParam(name = "userId", value = "用户ID", required = true)

多个参数一样的写法

实体类 entity

类: @ApiModel(value = "用户实体", description = "用户实体")

属性: @ApiModelProperty(value = "用户账号",required = true,dataType ="String")

required = true 表示必填，默认: false 不必填
hidden = true 表示隐藏该属性，默认: false隐藏

简单使用就到此结束了。

3.Knife4j 增强版部分功能使用

开启增强版功能，在:application.yml 中加入

knife4j:
  enable: true

在 Knife4jConfiguration 配置类中引入Knife4j提供的扩展类

 /*引入Knife4j提供的扩展类*/
    private final OpenApiExtensionResolver openApiExtensionResolver;

    public Knife4jConfiguration(OpenApiExtensionResolver openApiExtensionResolver) {
        this.openApiExtensionResolver = openApiExtensionResolver;
    }

对Knife4j提供的资源提供BasicHttp校验,保护文档

knife4j:
  enable: true
  basic:
    enable: true
    username: admin
    password: ldxdcxy

在访问就需要输入用户名跟密码

选择取消

开启刷新变量按钮：enableReloadCacheParameter: true

现在很多项目中都会从Header取值进行检验，判断请求是否合法

比如：通过jwt生成一个token 、自定义的 appSecret、自定义加密的MD5( appKey+ 时间戳)等等放在Header中，服务器从Header获取对应值进行校验，判断请求是否合法。

目前请求头部中是一片白板，任何信息没有，需要在 Knife4jConfiguration 类中做如下配置

添加参数名称

 /**
     * 添加接口请求头参数配置 没有的话 可以忽略
     */
    private List<Parameter> setHeaderToken() {
        List<Parameter> pars = new ArrayList<>();
        // token请求头
        String testTokenValue = "";
        ParameterBuilder tokenPar = new ParameterBuilder();
        Parameter tokenParameter = tokenPar
                .name("token")
                .description("Token Request Header")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .defaultValue(testTokenValue)
                .build();
        pars.add(tokenParameter);
        return pars;
    }

加入到Docket 中

.globalOperationParameters(setHeaderToken())

效果为：

完整代码是：

package com.ldxdcxy.demo.config.Knife4j;

import java.util.ArrayList;
import java.util.List;

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.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;


/**
 * Knife4j 配置
 * @author ldxdcxy
 */
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    /**
     * 分组名称
     */
    private String groupName="ldxdcxy";

    /*引入Knife4j提供的扩展类*/
    private final OpenApiExtensionResolver openApiExtensionResolver;


    public Knife4jConfiguration(OpenApiExtensionResolver openApiExtensionResolver) {
        this.openApiExtensionResolver = openApiExtensionResolver;
    }

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 配置api文档的分组
                .groupName(groupName)
                .select()
                //配置扫描路径
                .apis(RequestHandlerSelectors.basePackage("com.ldxdcxy.demo"))
                // 配置过滤哪些
                .paths(PathSelectors.any())
                .build()
                 //赋予插件体系
                .extensions(openApiExtensionResolver.buildExtensions(groupName))
                .globalOperationParameters(setHeaderToken());
    }
    /**
     * api基本信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfo("spring boot swagger-ui 文档",
                "spring boot swagger 测试",
                "v1.0",
                "https://doc.xiaominfo.com/",
                //作者信息
                new Contact("路灯下的程序猿", "https://mp.csdn.net/mp_blog/creation/editor/121809930", "xxxxx@qq.com"),
                "Apache 2.0",
                "https://mp.csdn.net/mp_blog/creation/editor/121809930",
                new ArrayList());
    }

    /**
     * 添加接口请求头参数配置 没有的话 可以忽略
     */
    private List<Parameter> setHeaderToken() {
        List<Parameter> pars = new ArrayList<>();
        // token请求头
        String testTokenValue = "";
        ParameterBuilder tokenPar = new ParameterBuilder();
        Parameter tokenParameter = tokenPar
                .name("token")
                .description("Token Request Header")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .defaultValue(testTokenValue)
                .build();
        pars.add(tokenParameter);
        return pars;
    }
}

版本1.9.6 也可以实现请求头部，去掉：yml文件中的 knife4j 的相关设置，去掉：Knife4jConfiguration 类中引入Knife4j提供的扩展类的相关信息，版本退回到1.9.6 就可以了。

knife4j 的增强版还有很多功能，比如：自定义文档、前端Ui的个性化配置、开启生产环境保护策略等等，有兴趣的可以 3.1 增强模式 | knife4j 查看对应的参数，设置在yml中

源码地址：spring boot 集成 Knife4j 2.0.7 实现API 文档https://gitee.com/ldxdcxy/spring-boot-demo-swagger.git