后端整合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. 结果展示