Java 后端整合 Swagger + Knife4j 接口文档
文章目录
- 一. 接口文档
- 1.1 什么是接口文档？
- 1.2 **为什么需要接口文档？**
- 1.3 **怎么做接口文档？**
- 1.4 **接口文档有哪些技巧？**
- 二. 后端整合 Swagger + Knife4j
- 2.1 Swagger
- 2.1.1 引入依赖
- 2.1.2 设置Swagger配置类
- 2.1.3 报错
- 2.2 Knife4j
- 2.2.1 引入依赖
- 2.2.2 在config目录（没有就新建）下创建Knife4j配置依赖，代码如下：
- 2.2.3 版本问题导致的报错
- 2.2.4 访问地址，**注意端口、实际的地址**
一. 接口文档
1.1 什么是接口文档？
什么是接口文档？写接口信息的文档，每条接口包括：
-
请求参数
-
响应参数
-
- 错误码
-
接口地址
-
接口名称
-
请求类型
-
请求格式
-
备注
who 谁用？一般是后端或者负责人来提供，后端和前端都要使用
1.2 为什么需要接口文档？
-
有个书面内容（背书或者归档），便于大家参考和查阅，便于 沉淀和维护 ，拒绝口口相传
-
接口文档便于前端和后端开发对接，前后端联调的 介质 。后端 => 接口文档 <= 前端
-
好的接口文档支持在线调试、在线测试，可以作为工具提高我们的开发测试效率
1.3 怎么做接口文档？
-
手写（比如腾讯文档、Markdown 笔记）
-
自动化接口文档生成：自动根据项目代码生成完整的文档或在线调试的网页。Swagger，Postman（侧重接口管理）（国外）；apifox、apipost、eolink（国产）
1.4 接口文档有哪些技巧？
Swagger 原理：
- 引入依赖（Swagger 或 Knife4j：https://doc.xiaominfo.com/knife4j/documentation/get_start.html）
- 自定义 Swagger 配置类
- 定义需要生成接口文档的代码位置（Controller）
- 千万注意：线上环境不要把接口暴露出去！！！可以通过在 SwaggerConfig 配置文件开头加上
@Profile({"dev", "test"})限定配置仅在部分环境开启 - 启动即可
- 可以通过在 controller 方法上添加 [@Api、@ApiImplicitParam(name ](/Api、@ApiImplicitParam(name ) = “name”,value = “姓名”,required = true) [@ApiOperation(value ](/ApiOperation(value ) = “向客人问好”) 等注解来自定义生成的接口描述信息
如果 springboot version >= 2.6，需要添加如下配置：
spring:
mvc:
pathmatch:
matching-strategy: ANT_PATH_MATCHER
二. 后端整合 Swagger + Knife4j
2.1 Swagger
2.1.1 引入依赖
<!-- swagger 接口文档 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2.1.2 设置Swagger配置类
然后是config文件的新建
package ***;
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.EnableSwagger2;
/**
* 自定义 Swagger 接口文档的配置
*/
@Configuration // 配置类
@EnableSwagger2 // 开启 swagger2 的自动配置
public class SwaggerConfig {
@Bean
public Docket docket() {
// 创建一个 swagger 的 bean 实例
return new Docket(DocumentationType.SWAGGER_2)
// 配置接口信息
.select() // 设置扫描接口
// 配置如何扫描接口
.apis(RequestHandlerSelectors
//.any() // 扫描全部的接口，默认
//.none() // 全部不扫描
.basePackage("") // 扫描指定包下的接口，最为常用
//.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口
//.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口
).paths(PathSelectors.any() // 满足条件的路径，该断言总为true
//.none() // 不满足条件的路径，该断言总为false（可用于生成环境屏蔽 swagger）
//.ant("/user/**") // 满足字符串表达式路径
//.regex("") // 符合正则的路径
).build();
}
// 基本信息设置
private ApiInfo apiInfo() {
Contact contact = new Contact("jin", // 作者姓名
"", // 作者网址
"@qq.com"); // 作者邮箱
return new ApiInfoBuilder().title("123") // 标题
.description("你若盛开，清风徐来") // 描述
.termsOfServiceUrl("https://github.com/") // 跳转连接
.version("1.0") // 版本
.license("Swagger-的使用(详细教程)").licenseUrl("123").contact(contact).build();
}
}
2.1.3 报错
如果你的springboot版本是大于等于2.4以上，大概率会出现一下报错：
在application.yaml配置文件中添加如下配置：
spring:
mvc:
pathmatch:
matching-strategy: ANT_PATH_MATCHER
2.2 Knife4j
2.2.1 引入依赖
<!--引入Knife4j的官方start包,Swagger2基于Springfox2.10.5项目-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<!--使用Swagger2-->
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.9</version>
</dependency>
2.2.2 在config目录（没有就新建）下创建Knife4j配置依赖，代码如下：
添加配置类，注意：basePackage 需要填写 controller 的路径
千万注意：线上环境不要把接口暴露出去！！！可以通过在 SwaggerConfig 配置文件开头加上 @Profile({"dev", "test"}) 限定配置仅在部分环境开启
package ***;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
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;
/**
* @author
* 自定义 Swagger 接口文档的配置
*/
/**
* @Description: 自定义 Swagger 接口文档的配置
*/
@Configuration
@EnableSwagger2WebMvc
@Profile({"dev", "test"}) //版本控制访问
public class SwaggerConfig {
@Bean(value = "defaultApi2")
public Docket defaultApi2() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// 这里一定要标注你控制器的位置
.apis(RequestHandlerSelectors.basePackage(".controller"))
.paths(PathSelectors.any())
.build();
}
/**
* api 信息
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("jin")
.description("jin接口文档")
.termsOfServiceUrl("https://github.com")
.contact(new Contact(""))
.version("1.0")
.build();
}
}
2.2.3 版本问题导致的报错
如果你的springboot版本是大于等于2.4以上，大概率会出现一下报错
需要配置，不然会和Swagger一样的报错
mvc:
pathmatch:
matching-strategy: ant_path_matcher
profiles:
active: dev
可以通过在 controller 方法上添加 @Api、@ApiImplicitParam(name = “name”,value = “姓名”,required = true) @ApiOperation(value = “向客人问好”) 等注解来自定义生成的接口描述信息。
千万注意：线上环境不要把接口暴露出去！！！可以通过在 SwaggerConfig 配置文件开头加上 @Profile({“dev”, “test”}) 限定配置仅在部分环境开启
去application.yml中修改默认配置，并在swaggerConfig中加上@Profile注解
（补充一下，一定要注意运行环境和扫描的controller包的路径。）
否则报出异常：
2.2.4 访问地址，注意端口、实际的地址
端口对应，正常访问http://localhost:8080/doc.html
如果配置类当中有配置路径，则需要加上
server:
port: 8888
servlet:
context-path: /api
该地址访问：http://localhost:8888/api/doc.html