接口文档[Knife4j]
接口文档是描述 API 接口的详细文档,通常用于沟通开发、测试和使用 API 的团队。一个好的接口文档不仅能够让开发人员明确接口的使用方法,还可以帮助使用者理解 API 的功能和预期行为。
Knife4j 使用,参考:https://doc.xiaominfo.com/docs/quick-start
swagger标准常用注解;
访问 http://ip:port/doc.html 即可查看接口文档
访问 http://ip:port/doc.html 即可查看接口文档
注解 | 标注位置 | 作用 |
---|---|---|
@Tag | controller 类 | 描述 controller 作用 |
@Parameter | 参数 | 标识参数作用 |
@Parameters | 参数 | 参数多重说明 |
@Schema | model 层的 JavaBean | 描述模型作用及每个属性 |
@Operation | 方法 | 描述方法作用 |
@ApiResponse | 方法 | 描述响应状态码等 |
方法一
添加依赖
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.4.0</version>
</dependency>
创建application.yaml文件
# springdoc-openapi项目配置
springdoc:
api-docs:
path: /api-docs # 配置 OpenAPI 文档的路径
swagger-ui:
path: /swagger-ui.html # 配置 Swagger UI 的路径
enabled: true # 启用 Swagger UI
# 定制文档基本信息
info:
title: API 文档标题 # 设置文档标题
description: API 文档描述 # 设置文档描述
version: 1.0.0 # 设置 API 版本
terms-of-service: https://example.com/terms # 服务条款 URL
# 关于开发者
contact:
name: 开发者姓名 # 开发者联系人姓名
url: https://example.com/contact # 联系方式 URL
email: [email protected] # 开发者联系邮箱
# 关于许可证
license:
name: Apache 2.0 # 许可证名称
url: https://www.apache.org/licenses/LICENSE-2.0.html # 许可证 URL
# 定制服务器基本信息
servers:
- url: http://localhost:8080 # 服务器 URL
description: 本地服务器 # 服务器描述
- url: https://api.example.com # 服务器 URL
description: 生产服务器 # 服务器描述
# 定制外部文档信息
external-docs:
description: 外部文档描述 # 外部文档描述
url: https://example.com/docs # 外部文档 URL
#这里定义了两个分组,可定义多个,也可以不定义
group-configs:
#分组名
- group: admin
#按路径匹配
pathsToMatch: /admin/**
#分组名
- group: user
#按包路径匹配
packagesToScan: com.hello.api.user
# knife4j的增强配置,不需要增强可以不配
knife4j:
enable: true
setting:
language: zh_cn
使用OpenAPI3的规范注解,注释各个Spring的REST接口
@RestController
@Tag(name = "名") //本controller类的介绍
public class BodyController {
@Operation(summary = "普通body请求") //方法的介绍
@PostMapping("/body")
public ResponseEntity<> body(@RequestBody FileResp fileResp){
return ResponseEntity.ok();
}
@Parameters({
@Parameter(name = "id", description = "员工id", in = ParameterIn.PATH,required = true) //参数的介绍
})
@Operation(summary="按照id查询员工信息")
@GetMapping("/employee/{id}")
public R get(@PathVariable("id") Long id){
//进行脱敏以后返回给前端
return R.ok(respVo);
}
}
@Schema(description = "员工修改提交的数据") //属性的描述
@Data
public class EmployeeUpdateVo {
@Schema(description = "员工id")
private Long id;
}
方法二
引入Maven 依赖
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.3.0</version>
</dependency>
创建配置类
@Configuration
public class Knife4jConfiguration {
//设置doc.html首先
@Bean
public OpenAPI openAPI() {
Contact contact = new Contact();
contact.setName("名字");
return new OpenAPI()
.info(new Info()
.title("hello-knife4j项目API")
.contact(contact)
.version("1.0")
.description("hello-knife4j项目的接口文档"));
}
//指定接口文档的分组
@Bean
public GroupedOpenApi userAPI(){
return GroupedOpenApi.builder()
.group("user")
.displayName("用户接口")
.pathsToMatch("/user/**").build();
}
@Bean
public GroupedOpenApi loginAPI(){
return GroupedOpenApi.builder()
.group("login")
.displayName("登录接口")
.pathsToMatch("/login/**").build();
}
}
启动项目
标签:Knife4j,description,接口,id,文档,com,public From: https://www.cnblogs.com/21CHS/p/18528878启动SpringBoot项目,访问http://localhost:8080/doc.html,观察接口文档。