后端整合Swagger+Knife4j接口文档

后端整合Swagger+Knife4j接口文档

接口文档介绍

1. 什么是接口文档：写接口信息的文档，条接口包括：
   • 请求参数
   • 响应参数
     • 错误码
   • 接口地址
   • 接口名称
   • 请求类型
   • 请求格式
   • 备注
2. 为什么需要接口文档
   • who用？后端提供，前后端都需要使用
   • 有一个书面归档，便于参考和查阅，沉淀和维护
   • 便于前端和后端的开发，联调的介质。后端=>接口文档<=前端
   • 在线测试，作为工具，提高开发速率
3. 怎么做接口文档
   • 手写（比如腾讯笔记，markdown笔记）
   • 自动化接口文档生成：根据项目代码生成完整的文档或在线联调工具Swagger，Postman（侧重接管理），apifox，apipost，eolink
4. Swagger接口的原理
   • 自定义Swagger配置类
   • 定义需要生成接口文档的代码位置(controller)

项目中使用Swagger+Knife4j接口文档

1. Swagger官方：https://swagger.io/
2. 项目中引入依赖

   <groupId>io.springfox</groupId>
           <artifactId>springfox-swagger2</artifactId>
           <version>2.7.0</version>
       </dependency>
       <dependency>
           <groupId>io.springfox</groupId>
           <artifactId>springfox-swagger-ui</artifactId>
           <version>2.7.0</version>
       </dependency>
   

3. 自定义Swagger配置类，在springBoot项目中使用springBoot的注解，生成一个swagger配置的bean。

   	package com.yupi.usercenter.config;
   
   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.service.Contact;
   import springfox.documentation.spi.DocumentationType;
   import springfox.documentation.spring.web.plugins.Docket;
   import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;
   
   /**
    * 自定义swagger的配置
    */
   @Configuration
   @EnableSwagger2WebMvc // Swagger的开关，表示已经启用Swagger
   public class SwaggerConfig {
       @Bean(value = "defaultApi2") //生成一个swagger的配置，框架扫描到这个配置，注入到swagger的对象中，就可以初始化一个文档
       public Docket createRestApi(){
           return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo())
                   .select()
                   //标注控制器的位置
                   .apis(RequestHandlerSelectors.basePackage("com.yupi.usercenter.controller"))
                   .paths(PathSelectors.any())
                   .build();
       }
   
       /**
        * api信息
        * @return
        */
       private ApiInfo apiInfo() {
           return new ApiInfoBuilder().title("用户中心")
                   .contact(new Contact("whale", "www.xxx.com", "xxx@qq.com"))
                   .description("这是用Swagger动态生成的用户中心接口文档")
                   .termsOfServiceUrl("NO terms of service")
                   .version("1.0")
                   .build();
       }
   }
   

   若springboot versio>=2.6,需要添加以下配置

     mvc:
      pathmatch:
        matching-strategy: ANT_PATH_MATCHER
   

4. 结果展示