SpringBoot3整合Knife4j

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

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

FF在路上

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值