spring boot集成Knife4j

文章目录

一、Knife4j是什么？

前言：
Spring Boot 版本建议 2.4.0~3.0.0之间
Spring Boot 版本 < 2.4 版本则建议选择Knife4j 4.0之前的版本
该示例springboot版本为2.7.18

Knife4j是一个基于Swagger构建的开源JavaAPI文档工具，它为Java开发者提供了生成、展示和调试API文档的功能。它提供了一套美观且功能强大的界面，可以自动生成API文档，并支持接口分组、参数设置、请求示例、响应模型配置等高级功能。

Knife4j 在更名为Knife4j之前,原来的名称是叫swagger-bootstrap-ui，这是两种不一样风格的Ui,对比情况如下

二、使用步骤

1.引入依赖

#  注意：引入knife4j后会自动引入swagger相关依赖，因此无需再手动引入swagger相关依赖，否则会引起版本冲突
        <dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi2-spring-boot-starter</artifactId><version>4.0.0</version></dependency>

2.新增相关的配置类

package com.xxxx;

import org.springframework.core.annotation.Order;
import springfox.documentation.service.Contact;
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 ="defaultApi1")
    @Order(1)
    public Docket defaultApi1(){
        Docket docket=new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())//分组名称.groupName("用户").select()//这里指定Controller扫描包路径.apis(RequestHandlerSelectors.basePackage("om.xx.demo.controller.sys")).paths(PathSelectors.any()).build();return docket;}

    @Bean(value ="defaultApi2")
    @Order(2)
    public Docket defaultApi2(){
        Docket docket=new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())//分组名称.groupName("测试").select()//这里指定Controller扫描包路径.apis(RequestHandlerSelectors.basePackage("com.xx.demo.controller.test")).paths(PathSelectors.any()).build();return docket;}
    private ApiInfo apiInfo(){return new ApiInfoBuilder().title("标题")//标题.contact(new Contact("admin","http://127.0.0.1",""))//作者.description("简介API文档")//简介.termsOfServiceUrl("")//服务URL.version("1.0")//版本.build();}}

3.添加配置信息

在application.properties或application.yml中配置Knife4j相关的属性（可选，根据需要配置）

     knife4j:
          # 增强功能开启
         enable: true
         # 开启生产环境屏蔽（该选项配置后，无法访问页面）
         production: true
         # 开启Swagger的Basic认证功能,默认是false，配置后登录才可访问页面
         basic:
                enable: true
             #Basic认证用户名
             username: admin
             #Basic认证密码
                password:123456

4.新建测试类

package com.xx.demo.controller.test;

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

@Api( tags ="测试接口")
@RestController
public class HelloController {

    @GetMapping("/test")
    @ApiOperation("查test列表")
    public String test(){return"hello";}}

5. 启动项目

启动项目后，访问http://ip:port/doc.html,输入用户名密码后可查看

三、其他版本集成时常见异常

1. Failed to start bean ‘documentationPluginsBootstrapper

解决办法:再启动类上加@EnableWebMvc

2.访问地址后报404

package com.xx.demo.config;import org.springframework.context.annotation.Configuration;import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

@Configuration
public class WebMvcConfig extends WebMvcConfigurationSupport {

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