Part14 - Swagger+Apifox
大约 5 分钟
Part14 - Swagger+Apifox
1. 生成接口文档
1.1. Swagger接口文档
前言
Swagger 是一个开源的 API 设计和文档工具，它可以帮助开发人员更快、更简单地设计、构建、文档化和测试 RESTful API。Swagger 可以自动生成交互式 API 文档、客户端 SDK、服务器 stub 代码等，从而使开发人员更加容易地开发、测试和部署 API。
说明：https://apifox.com/apiskills/what-is-swagger/
1. 导入依赖（也要清楚一些非必要依赖）
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.5.0</version>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
<version>2.5.0</version>
</dependency>
- 在config包中导入配置类
@Configuration
public class SwaggerConfig {
@Bean
public OpenAPI springShopOpenAPI() {
return new OpenAPI()
.info(new Info().title("Spring Boot 中使用 Swagger UI 构建 RESTful API")//文档信息
.contact(new Contact().email("798391056@qq.com"))//联系信息
.description("中州养老AI+IOT平台提供的 RESTful API")//文档描述
.version("v1.0.0")//文档版本
.license(new License().name("Apache 2.0").url("http://springdoc.org")))//许可信息
.externalDocs(new ExternalDocumentation()//文档外链
.description("学习笔记")
.url("http://www.yangeit.cn:21010/expand/schoolsx/zzoldpeople20/"));
}
}
3. 如果存在统一异常处理类，需要加入@Hidden注解，避免报错
@Hidden
@RestControllerAdvice
public class GlobalExceptionHandler {
//处理异常
@ExceptionHandler
public AjaxResult ex(BaseException e){//方法形参中指定能够处理的异常类型
e.printStackTrace();//打印堆栈中的异常信息
//捕获到异常之后，响应一个标准的Result
// if (不友好的信息){
// return AjaxResult.error("正忙尼！ 不用急，稍后再试！！！");
// }
return AjaxResult.error(e.getMessage());
}
}
4. 在拦截器配置类中，需要将swagger的拦截器排除掉
@Configuration//告诉Spring这是一个配置类
public class WebConfig implements WebMvcConfigurer {
@Autowired
LoginCheckInterceptor loginCheckInterceptor;
@Override
public void addInterceptors(InterceptorRegistry registry) {
//todo yangeit 添加拦截器 /customer/**
registry.addInterceptor(loginCheckInterceptor)
.addPathPatterns("/customer/**")//拦截微信所有请求
.excludePathPatterns("/customer/user/login",
"/customer/roomTypes",
"/error",
"/swagger-ui/**", "/v3/**");
}
}
5. 访问地址：http://localhost:9995/swagger-ui/index.html
6. 使用swagger测试获取房型的接口
1.2. SpringDocOpenAPI常见注解
前言
从上图我们可以看到，有的方法和模块有中文解释，有的没有，这是怎么实现的呢？
其实可以通过Swagger3的注解来实现（注意：这里和SpringBoot2.0的Swagger2.0不同哦 ）
那有哪些常用的注解呢？👇
1. @Tag注解：
@Tag 用于描述模块，通常用于类上。
常用的属性包括：
name：表示模块名称。
description：表示模块的描述。
示例👇 
- @Operation 注解：
@Operation 用于描述单个操作（即 API 端点）。
最常用的属性包括：
summary：表示操作的摘要，通常不要太长。
description：用于描述操作的细节，例如限制、返回值等。
hidden：表示是否隐藏此 API。
示例👇
3. @Parameter 注解：
@Parameter 用于描述请求参数或响应实体中的属性。
常用的属性包括：
name：表示参数名称。
description：表示参数的描述。
required：表示参数是否为必需的。
in：表示参数的位置，例如 query、path、header、cookie、body 等。
schema：表示参数的数据类型和格式。
示例👇 
4. @Schema 注解：
@Schema 用于描述模型属性，例如请求参数、响应实体等。
常用的属性包括：
name：表示属性名称。
title：表示属性的标题。
description：表示属性的描述。
type：表示属性的数据类型，例如字符串、整数、布尔值等。
format：表示属性的格式，例如日期、时间等。
example：表示属性的示例值。
required：表示属性是否为必需的。
示例👇
给每个Controller每个方法都加上注解，可以使用ai来写 👇
1.3. apifox软件对接
前言
1.4. apifox完善接口文档
前言
截止到现在为止，我们完成了apifox的导入配置，接下来我们需要导出接口文档，方便我们以后查看。
我们需要给每个接口配上请求参数的示例值和响应的示例值。有助于生成完善的接口文档。
1. 生成请求参数的示例值
2. 生成响应的示例值
这样讲所有的接口都完善好，然后导出接口文档，我们看看效果。 
好了，大家开始改造把！！！
总结
课堂作业
- 思考下，为什么要将接口文档写的这么详细，程序已经完成了，有必要吗？？🎤