文章目录
一、前言
1. API 文档自动生成
2. 交互式 API 测试
3. API 设计和开发协作
二、使用方法
1.导入依赖
2.文档配置
3.常见注解
4.效果展示
5.访问路径
一、前言
为了方便后端人员进行进行接口测试，swagger就此诞生
1. API 文档自动生成
- 减少文档编写工作：通过在代码中使用注解，Swagger 可以自动生成详细的 API 文档，减少了手动编写文档的工作量。
- 保持文档与代码同步：由于文档是直接从代码生成的，因此可以确保文档总是与实际的 API 实现保持一致。
2. 交互式 API 测试
- 实时测试 API：Swagger UI 提供了一个基于浏览器的界面，允许开发者直接从浏览器调用 API 并查看响应结果，这有助于快速测试 API 功能。
- 参数输入与验证：用户可以直接在界面上输入参数并发送请求，Swagger 会自动处理参数格式和验证。
3. API 设计和开发协作
- 统一的 API 规范：Swagger 使用 OpenAPI 规范（以前称为 Swagger 规范），这是一种标准的 API 描述格式，使得团队成员可以更容易理解和遵循 API 设计。
- 前后端分离开发：前端和后端开发者可以通过 Swagger 文档进行沟通，即使在后端 API 还未完成时，前端也可以开始基于文档进行开发。
二、使用方法
1.导入依赖
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.3.0</version></dependency><dependency><groupId>com.fasterxml.jackson.core</groupId><artifactId>jackson-core</artifactId><version>2.15.2</version> </dependency>2.文档配置
import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;@Configuration
public class OpenApiConfig {@Beanpublic OpenAPI springShopOpenAPI() {return new OpenAPI()// 接口文档标题.info(new Info().title("在线考试系统API接口文档")// 接口文档简介.description("这是基于Knife4j OpenApi3的在线考试系统接口文档")// 接口文档版本.version("v1.0")// 开发者联系方式.contact(new Contact().name("黄宏保").email("3111871135@qq.com"))).externalDocs(new ExternalDocumentation().description("在线考试系统接口文档")//swagger-ui文档地址.url("http://127.0.0.1:8088"));}@Beanpublic GroupedOpenApi adminApi() {return GroupedOpenApi.builder().group("管理员管理模块").pathsToMatch("/user/**","/admin/**").build();}@Beanpublic GroupedOpenApi teacherApi() {return GroupedOpenApi.builder().group("教师管理模块").pathsToMatch("/user/**", "/teacher/**").build();}@Beanpublic GroupedOpenApi studentApi() {return GroupedOpenApi.builder().group("学生管理模块").pathsToMatch("/user/**", "/student/**").build();}
}
application.yaml配置
springdoc:swagger-ui:path: /swagger-ui.html # 自定义Swagger前端请求路径tags-sorter: alphaoperations-sorter: alphaapi-docs:path: /v3/api-docs # Swagger后端请求地址enabled: true # 是否开启文档功能# knife4j相关配置
knife4j:enable: true # 开启knife4j，无需添加@EnableKnife4j注解setting:language: zh_cn # 中文
3.常见注解
@Tag(name = "用户管理")//用于在控制器类上标注，指示该控制器的相关信息
@Operation(summary = "登录")//用于在控制器方法上标注，指示该方法的作用、描述等
@Schema(description = "用户信息")//在DTO类上标注，用于描述一个实体类
@Schema(description = "用户信息")//用于描述实体类的属性(自己定义的接收变量)，即类的字段
@Parameter(description = "邮箱") //定义在控制层方法的参数上
4.效果展示
5.访问路径
swagger-ui路径:http://localhost:8080/swagger-ui/index.html
swagger文档路径:http://127.0.0.1:8080/doc.html#/home