Spring Boot整合Knife4j-2.0.7

为什么要做囚徒

已于 2024-06-12 15:04:39 修改

阅读量2.9k

点赞数 1

于 2023-05-27 13:11:52 首次发布

本文链接：https://blog.csdn.net/CSDN_LJK/article/details/130900151

版权

SpringBoot 专栏收录该内容

15 篇文章 0 订阅

订阅专栏

文章目录

一、 Knife4j简介
二、 Spring Boot整合Knife4j
三、导入到postman

一、 Knife4j简介

Kinfe4j(naɪf),像一把匕首一样小巧,轻量,并且功能强悍。官网的介绍如下：

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包即可,因此分离前后端)

官网入口

二、 Spring Boot整合Knife4j

Knife4j自2.0.6版本开始,将目前在Ui界面中一些个性化配置剥离,开发者可以在后端进行配置，并且提供的knife4j-spring-boot-strater组件自动装载。

以下示例是Knife4j增强模式

1. 引入依赖

在maven项目的pom.xml中引入Knife4j的依赖包，代码如下：

<!--引入knife4j启动器-->
<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>knife4j-spring-boot-starter</artifactId>
	<version>2.0.7</version>
</dependency>

其中springboot版本是2.7.5

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.7.5</version>
</parent>

2. 配置Knife4j

创建Swagger配置依赖，代码如下：

@Configuration
@EnableSwagger2WebMvc
@AllArgsConstructor
public class SwaggerConfig {

    /**
     * 引入Knife4j提供的扩展类
     * OpenApiExtensionResolver辅助类需要配置knife4j.enable=true才能自动@Autowired
     * @AllArgsConstructor这个注解就是注入，无需再额外添加@Autowired
     */
    private final OpenApiExtensionResolver openApiExtensionResolver;


    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //加了ApiOperation注解的类，生成接口文档
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //包下的类，生成接口文档
                //.apis(RequestHandlerSelectors.basePackage("com.xmc.knife4j.controller"))
                .paths(PathSelectors.any())
                .build()
                // buildExtensions方法需要传入分组名称,该分组名称主要是为了区分开发者在构建自定义文档时，在不同的Docket逻辑分组下进行区别显示
                .extensions(openApiExtensionResolver.buildExtensions("medical-search-serve"))
                .directModelSubstitute(java.util.Date.class, String.class)
                .securitySchemes(security());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("spring-boot-knife4j")
                .description("spring-boot-knife4j文档")
                .version("1.0")
                .build();
    }

    private List<ApiKey> security() {
        return ListUtil.list(true,new ApiKey("token", "token", "header"));
    }
}

3. 放行Knife4j请求

@Configuration
public class WebMvcConfig extends WebMvcConfigurationSupport {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

}

4. 使用Knife4j注解标记接口

@Api(tags = "测试knife4j")
@RestController
@RequestMapping("/api")
public class ApiController {

    @ApiOperation("hello请求")
    @PostMapping("hello")
    public String hello(@RequestBody User user) {
        return user.getName() + ":" + user.getSex();
    }
}

@ApiModel
@Data
public class User {

    @ApiModelProperty(value = "姓名", required = true)
    private String name;

    @ApiModelProperty(value = "性别", required = true)
    private String sex;

}

5. application.yml配置如下

server:
  port: 8080

knife4j:
  enable: true
  basic:
    enable: false
    username: admin
    password: admin
  setting:
    enableFooter: false

这里列举一些常见的配置，如需更加详细的配置参考官网

属性	默认值	说明值
knife4j.enable	false	是否开启Knife4j增强模式
knife4j.cors	false	是否开启一个默认的跨域配置,该功能配合自定义Host使用
knife4j.production	false	是否开启生产环境保护策略,详情参考文档
knife4j.basic		对Knife4j提供的资源提供BasicHttp校验,保护文档
knife4j.basic.enable	false	关闭BasicHttp功能
knife4j.basic.username		basic用户名
knife4j.basic.password		basic密码