SpringBoot使用knife4j(基于Swagger)生成接口文档

1.什么是swagger?

Swagger2是一个用于生成、发布和共享RESTful风格的API文档的标准，是一个开源的项目。

Swagger2主要为了提高API文档的可读性和可维护性，同时还保留了Swagger 1.x的优点，如及时性、规范性、一致性和可测性。它支持多种编程语言，包括Java，Python，PHP，C#，Go等，并且可以与其他开发工具（如Eclipse，IntelliJ IDEA）集成。

Swagger2的优点包括：

• 生成的文档易于理解和维护，使得API的使用者可以轻松地使用和调用API。
• 支持多种编程语言，使得API可以轻松地与其他系统进行集成。
• 具有良好的跨语言性，可以轻松地将文档翻译成其他语言。
• 可以与其他工具集成，如Postman，以便进行自动化测试。
• 可以方便地在文档页面上进行测试，使得测试人员可以快速地理解和调用API。

2.聊聊基于swagger2的knife4j

        由于直接使用swagger2是比较麻烦的因此我们一般会使用基于swagger2的框架knife4j,它不仅操作简单而且相比于swagger2又添加了一些功能例如接口搜索功能,同时也支持离线文档导出Markdown,Html,Word,OpenApi的jison,符合国人的开发习惯。

3.使用knife4j时的注意事项

如果SpringBoot的版本在2.6.x后,SpringBoot会和swagger2出现不兼容的情况，启动项目的时候会报错，下图为报错信息:

进行一下操作可以解决此类为题:

第一种解决方案:

在SpringBoot启动类或者是WebMvcConfig配置类上直接加入@EnableWebMvc注解即可解决。

第二种解决方案:

在application.yml中加入配置:

spring
 mvc:
  pathmatch:
   matching-strategy: ant_path_matcher

  注:直接粘贴代码的话需要注意下格式,yml对文件的格式是有要求的。  

生成接口文档接口第一步:导入knife4j的依赖

这里我导入的是3.0.2版本的依赖:

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

生成接口文档接口第二步:导入和knife4j相关的配置类

具体参考一下代码:

package edu.pdsu.reggie.config;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import edu.pdsu.reggie.common.JacksonObjectMapper;
import lombok.extern.slf4j.Slf4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.converter.HttpMessageConverter;
import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
import org.springframework.web.servlet.HandlerExceptionResolver;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
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.EnableSwagger2;

import java.util.List;

/**
 * @BelongsProject: reggie_take_out
 * @BelongsPackage: edu.pdsu.reggie.config
 * @Author: RDS
 * @Version: 1.0
 */
@Configuration
@Slf4j
@EnableSwagger2
@EnableKnife4j
public class WebMvcConfig implements WebMvcConfigurer{
    /**
     * @description:设置静态资源映射(静态资源不放到static中需要进行配置)
     * @param: [registry]
     * @return: void
     **/
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        log.info("开始进行静态资源映射...");
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

    @Bean
    public Docket createRestApi() {
        // 文档类型
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("edu.pdsu.reggie.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档标题")
                .version("版本信息")
                .description("接口文档描述")
                .build();
    }


}

生成接口文档接口第三步:启动项目并访问链接

http://localhost:8080/doc.html

接口文档生成完毕

 4.导出接口文档

5.knife4j常用的注解

注解	说明
@Api	用在请求类上,表示对类的说明
@ApiModel	用在类上,通常为实体类,表示一个返回响应数据的信息
@ApiModelProperty	用在属性上,描述响应类的属性
@ApiOperation	用在请求方法上,对方法进行说明
@ApilmplicitParams	用在请求方法上,表示一组参数说明
@ApilmplicitParam	用在@ApilmplicitParams注解中,对一个请求参数进行解释

按照规定使用Knife4j的这些可以让生成的接口文档更加的直观,标准,大家可以试着做一下