springboot整合knife4j

一、Swagger

1. Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务(官网地址：https://swagger.io/)。

2. Swagger只需要按照它底层的规范去定义接口及接口的相关信息，再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成在线接口调试页面等等。Swagger 是在开发阶段使用的框架，帮助后端开发人员做后端的接口测试

3. swagger的作用：

   • 1. 使得前后端分离开发更加方便，有利于团队协作
   • 2. 接口的文档在线自动生成，降低后端开发人员编写接口文档的负担
   • 3. 功能测试 。（可以代替potman（一款测试app）的作用）

4. Spring已经将Swagger纳入自身的标准，建立了Spring-swagger项目，现在叫Springfox。通过在项目中引入Springfox ，即可非常简单快捷的使用Swagger。这里可以参考青哥的一篇博客springboot继承swagger-ui。需要注意的是，使用的版本需要对应，不同的版本的注解，可能会存在细微的差距。

二、Knife4j

1. knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望它能像一把匕首一样小巧,轻量,并且功能强悍（目前，一般都会使用knife4j框架）

2. knife4j的优点：

   • Knife4j 功能强大，易于操作。
   • Knife4j 的UI界面非常美观，使用非常流畅。
   • Knife4j 可以高度定制化，让其符合你的项目需求，提升用户体验。
   • Knife4j 的支持性比较好，可以满足大部分的开发需求。

二、1、speingboot中使用knife4j

1. 在pom文件中导入 knife4j 的maven坐标：(springboot的版本用的是2.7.16）

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

2. 创建knife4j的配置类中加入 knife4j 相关配置：
   • 1. 首先配置一个配置类，然后让其继承WebMvcConfigurationSupport
   • 2. 修改docket方法里面的basePackage方法，修改自己项目的controller层的路径
   • 3. 设置静态资源的映射（如果不设置，就会无法访问）
   • 4. 访问路径为：http://localhost:8080/doc.html（项目的访问路径后面+doc.html）

@Configuration
public class WebMvcConfiguration extends WebMvcConfigurationSupport {


    /**
     * 注册自定义拦截器
     *
     * @param registry
     */
    @Override
    protected void addInterceptors(InterceptorRegistry registry) {
        // 添加自定义拦截器
//        registry.addInterceptor(new MyInterceptor());
    }



    /**
     * 通过knife4j生成接口文档
     * @return
     */
    @Bean
    public Docket docket() {
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("测试接口文档")  //设置接口文档的标题
                .version("1.0") // 接口文档的版本
                .description("测试接口文档") // 接口文档的描述信息
                .build();
        Docket docket = new Docket(DocumentationType.SWAGGER_2) //DocumentationType.SWAGGER_2：表示指定swagger的版本
                .apiInfo(apiInfo)   // 设置生成的接口文档的信息
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.knife.controller"))  // 指定生成接口文档需要扫描的包
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

    /**
     * 设置静态资源映射
     * @param registry
     */
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

    /**
     * 扩展Spring MVC框架的消息转化器
     * @param converters
     */
    @Override
    protected void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
        // 添加自定义消息转换器
        //1.创建一个消息转换器对象
        //2. 需要为消息转换器设置一个对象转换器，对象转换器可以将Java对象序列化为json数据
        //3. 将自己的消息转化器加入容器中（消息转换器是有顺序地，而且里面还有很多的，索引0的作用就是把我们新加入的转换器放在第一个）
//        converters.add(new MyMessageConverter());
    }
}

knife4j常用注解

通过注解可以控制生成的接口文档，使接口文档拥有更好的可读性，常用注解如下：

注解	说明
@Api	用在类上，例如Controller，表示对类的说明
@ApiModel	用在类上，例如entity、DTO、VO
@ApiModelProperty	用在属性上，描述属性信息
@ApiOperation	用在方法上，例如Controller的方法，说明方法的用途、作用

@APi注解

1. @APi注解一般用在controller层下的控制类。此注解的tags属性可配置模块名称，可以在每个模块名称之前添加数字，则API文档会根据此名称的序号，进行升序排列。
   
   

@ApiModel与@ApiModelProperty注解

1. @ApiModel注解是用在接口相关的实体类上的注解，它主要是用来对使用该注解的接口相关的实体类添加额外的描述信息。

   • value属性就是对所需要特别说明的接口相关实体类进行描述。
   • description属性就是对所需要特别说明的接口相关实体类进行较长的描述。

2. @ApiModelProperty：添加在pojo类的属性上的注解,用于对请求参数或响应结果中的某个属性进行说明,主要通过其value属性配置描述文本,并可通过example属性配置示例值

@ApiOperation注解

1. @ApiOperation注解在用于方法上，可以用来说明方法的用途、作用。
   

三、WebMvcConfigurationSupport类使用的注意事项：

1. 在Spring Boot中，如果你想自定义WebMvc的配置，可以通过继承WebMvcConfigurationSupport类来实现。继承该类可以让你完全控制WebMvc的配置，包括添加拦截器、自定义消息转换器等。但是需要注意的是，继承WebMvcConfigurationSupport类会导致Spring Boot的自动配置类WebMvcAutoConfiguration失效。（springboot项目中没有使用到WebMvcConfigurerAdapter、WebMvcConfigurer、WebMvcConfigurationSupport
   WebMvcAutoConfiguration这几个类，springboot就会自动启用WebMvcAutoConfiguration类做自动加载；项目中的配置都是默认的，比如静态资源文件的访问等等）

以下是一个示例代码，展示了如何在Spring Boot中使用WebMvcConfigurationSupport类：

@Configuration
public class MyWebMvcConfig extends WebMvcConfigurationSupport {

    @Override
    protected void addInterceptors(InterceptorRegistry registry) {
        // 添加自定义拦截器
        registry.addInterceptor(new MyInterceptor());
    }

    @Override
    protected void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        // 添加自定义消息转换器
        converters.add(new MyMessageConverter());
    }
}

1. 在上面的示例中，我们创建了一个名为MyWebMvcConfig的配置类，继承自WebMvcConfigurationSupport。在该类中，我们重写了addInterceptors方法和configureMessageConverters方法，分别添加了自定义的拦截器和消息转换器。
2. 如果你想使用WebMvcConfigurationSupport类，你需要手动配置所有的WebMvc相关的配置，包括拦截器、消息转换器等。如果你只需要对某些配置进行自定义，可以考虑使用其他方式，比如实现WebMvcConfigurer接口。