1. 引入依赖
<!--swagger-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.5.0</version>
</dependency>
2. yml配置文件
# 配置springdoc-openapi,用于文档化和访问API
springdoc:
# 配置Swagger UI的访问路径和排序方式
swagger-ui:
path: /swagger-ui.html # Swagger UI的访问路径
tags-sorter: alpha # 按字母顺序排序标签
operations-sorter: alpha # 按字母顺序排序操作
# 配置API文档的访问路径
api-docs:
path: /v3/api-docs # API文档的访问路径
# 配置API分组,用于组织和管理API
group-configs:
- group: 'default' # API分组名称
paths-to-match: '/**' # 匹配所有路径
packages-to-scan: com.feng.mybatisplusdemo1.contraller # 扫描的包,用于自动发现API
# knife4j的增强配置,不需要增强可以不配
knife4j:
enable: true
setting:
language: zh_cn
3. 常用注解
3.1 类级别注解
@Tag
用于为API操作分组。
@Tag(name = "测试类",description = "测试swagger")
@RestController
@RequestMapping("/test")
public class TestController {
}
属性:
- name:标签名。
- description:标签描述。
3.2 方法级别注解
@Operation
用于描述控制器类中的单个操作。
@Operation(summary = "测试方法",description = "测试swagger方法的描述")
@PostMapping("/{id}")
public void test(@Parameter(description = "id",required = true) @PathVariable("id") Long id){
System.out.println("test================"+id);
}
属性:
- summary:简短描述。
- description:详细说明。
- tags:标签,用于分类API。
- responses:响应描述。
@ApiResponses
用于描述API操作的响应。
@Tag(name = "测试类",description = "测试swagger")
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "成功", content = @Content(mediaType = "application/json", schema = @Schema(implementation = User.class))),
@ApiResponse(responseCode = "400", description = "请求参数错误"),
@ApiResponse(responseCode = "404", description = "找不到资源"),
@ApiResponse(responseCode = "500", description = "服务器内部错误")
})
@RestController
@RequestMapping("/test")
public class TestController {
@Operation(summary = "测试方法",description = "测试swagger方法的描述")
@PostMapping("/{id}")
public void test(@Parameter(description = "id",required = true) @PathVariable("id") Long id){
System.out.println("test================"+id);
}
}
属性:
- value:包含多个@ApiResponse注解。
@ApiResponse
用于描述单个响应。。
属性:
- responseCode:HTTP状态码。
- description:描述信息。
- content:响应内容类型和模式。
3.3 参数级别注解
@Parameter
用于描述单个参数
@Operation(summary = "测试方法",description = "测试swagger方法的描述")
@PostMapping("/{id}")
public void test(@Parameter(description = "id",required = true) @PathVariable("id") Long id){
System.out.println("test================"+id);
}
属性:
- name:参数名。
- description:参数描述。
- required:是否必须参数。
- schema:参数模式。
@Parameters
用于描述多个参数
@PutMapping("{id}/dedeuction/{balance}")
@Operation(summary = "余额修改接口",description = "通过ID扣减相应金额")
@Parameters({
@Parameter(name = "id",description = "用户ID" ),
@Parameter(name = "balance",description = "修改金额")
})
public void updateBalanceById(@PathVariable("id") Long id,@PathVariable("balance") Integer balance){
System.out.println("修改ID:"+id+"用户金额,扣减:"+balance);
}
属性:
- value:包含多个@Parameter注解。
3.4 模型类注解
@Schema
用于描述模型类和字段的信息
@Data
@Schema(description = "用户VO实体")
public class UserVO {
@Schema(description = "用户id")
private Long id;
@Schema(description = "用户名")
private String username;
@Schema(description = "详细信息")
private String info;
@Schema(description = "使用状态(1正常 2冻结)")
private Integer status;
@Schema(description = "账户余额")
private Integer balance;
}
属性:
- description:字段描述。
- example:示例值。
- required:是否必须字段。
- type:字段类型。
4. 访问界面
http://localhost:8080/doc.html
原文链接:https://blog.youkuaiyun.com/qq_51774011/article/details/140594038