Swagger和Knife4j在springboot中的配置和使用

可以理解为Knife4j是对swagger进行了封装和增强。我们需要知道一些基础知识：

        1.Knife4j使用两种规范，一个是OpenAPI2，一个是OpenAPI3，其最明显的区别就是它们在java文件中标记时使用的注解不同，并且官方更倾向于推荐使用3的规范。

        2.对于Knife4j来说，其依赖中包含了swagger的依赖也就是springdoc的相关依赖，所以要使用Knife4j的话只需要导入Knife4j的依赖，并不需要导入其封装的swagger相关依赖。

        3.springboot的版本其实和Knife4j的版本和标准是有对应关系的，但是对于springboot2.4以上的版本其实我们最常用的就是Knife4j的纯UI，并不太使用它的增强功能，所以对于大多数人的项目来说，其实考虑一下Knife4j的规范，然后导入最新的Knife4j依赖就可以了。

---

具体如下（使用OpenAPI3，也就是3的规范）：

        1.引入Knife4j3依赖：

                现在是2014.1.18日，较新的依赖是4.3.0。

        对于springboot3.x的版本，依赖为：

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

        对于springboot2.x的版本，依赖为：

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

        2.配置yml文件（springboot2和3都一样）：

                加入如下配置：

#springdoc相关配置
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
    enabled: true
  api-docs:
    path: /v3/api-docs
    enabled: true
  group-configs:
    - group: "管理端"
      paths-to-match: '/admin/**'
      packages-to-scan: com.my.controller
    - group: "用户端"
      paths-to-match: '/user/**'
      packages-to-scan: com.my.controller

knife4j:
  enable: true
  setting:
    language: zh_cn

3.创建一个config类，配置一下相关信息，主要为设置静态资源映射，不然打不开文档。（springboot2和3都一样）

        3.1 在config类中创建一个WebConfig类：

代码如下：

        1.其中addResourceHandlers方法为设置静态资源映射，保证可以打开文档。

        2.其中springShopOpenAPI方法和info方法为设置接口文档的基本信息，这个有没有都行，加上了可以让你的文档更好看，信息更全面。

        3.其中addInterceptors方法和JwtTokenAdminInterceptor jwtTokenAdminInterceptor语句这是我自己定义了一个拦截器，直接把这些删了就行。

package com.sky.config;

import com.sky.interceptor.JwtTokenAdminInterceptor;
import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

@Slf4j
@Configuration
public class WebConfig extends WebMvcConfigurationSupport {
    @Autowired
    private JwtTokenAdminInterceptor jwtTokenAdminInterceptor;

    /**
     * 注册自定义拦截器
     *
     * @param registry
     */
    protected void addInterceptors(InterceptorRegistry registry) {
        log.info("开始注册自定义拦截器...");
        registry.addInterceptor(jwtTokenAdminInterceptor)
                .addPathPatterns("/admin/**")
                .excludePathPatterns("/admin/employee/login");
    }

    private Info info(){
        return new Info()
                .title("苍穹外卖API接口文档")
                .description("苍穹外卖API接口文档")
                .version("v2.0.0")
                .contact(new Contact().name("Me").email("lalala@qq.com"));
    }
    @Bean
    public OpenAPI springShopOpenAPI() {
        return  new OpenAPI()
                .info(info())
                .externalDocs(new ExternalDocumentation());
    }
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        registry.addResourceHandler("/favicon.ico")//favicon.ico
                .addResourceLocations("classpath:/static/");
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
    }
}