API接口文档 Swagger&Knife4j 的用法

Swagger 和 Knif4j 是用于生成 API 文档的工具，它们可以通过注释来描述接口。以下是一些常用的注释和它们的用法的详细解释。

pom.xml文件配置

<!--swagger-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>4.1.0</version>
</dependency>
<!--web-->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

按照下面的使用说明，配置好后访问：http://127.0.0.1:8080/doc.html

Swagger 注释

Swagger 注释通常使用 @Api、@ApiOperation、@ApiParam 等注释来描述 RESTful API。以下是一些常用的注释及其用法：

1. @Api

• 描述：该注释用于类上，表示这是一个 API 控制器。
• 用法：

  import io.swagger.annotations.Api;
  
  @Api(value = "用户管理", tags = {"用户"})
  @RestController
  @RequestMapping("/users")
  public class UserController {
      // ...
  }
  

2. @ApiOperation

• 描述：用于方法上，描述该 API 方法的功能。
• 用法：

  import io.swagger.annotations.ApiOperation;
  
  @ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户详细信息")
  @GetMapping("/{id}")
  public User getUserById(@PathVariable Long id) {
      return userService.getUserById(id);
  }
  

3. @ApiParam

• 描述：用于方法参数上，描述参数的含义、是否必填等。
• 用法：

  import io.swagger.annotations.ApiParam;
  
  @GetMapping("/{id}")
  public User getUserById(@ApiParam(value = "用户ID", required = true) @PathVariable Long id) {
      return userService.getUserById(id);
  }
  

4. @ApiResponse

• 描述：用于描述 API 方法的响应信息。
• 用法：

  import io.swagger.annotations.ApiResponse;
  import io.swagger.annotations.ApiResponses;
  
  @ApiResponses(value = {
      @ApiResponse(code = 200, message = "成功获取用户信息"),
      @ApiResponse(code = 404, message = "用户未找到")
  })
  @GetMapping("/{id}")
  public User getUserById(@PathVariable Long id) {
      return userService.getUserById(id);
  }
  

Knif4j 注释

Knif4j 是一个 Swagger 的增强工具，提供了更好的用户体验。它通常使用与 Swagger 相同的注释，但也有一些额外的功能。

1. @ApiImplicitParam

• 描述：用于在方法上定义一个或多个参数，不需要在方法参数列表中声明。
• 用法：

  import io.swagger.annotations.ApiImplicitParam;
  import io.swagger.annotations.ApiImplicitParams;
  
  @ApiImplicitParams({
      @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path"),
      @ApiImplicitParam(name = "name", value = "用户名称", required = false, dataType = "String", paramType = "query")
  })
  @GetMapping("/{id}")
  public User getUserById(@PathVariable Long id, @RequestParam(required = false) String name) {
      return userService.getUserById(id);
  }
  

2. @ApiModel

• 描述：用于描述模型对象，通常配合 @ApiModelProperty 使用。
• 用法：

  import io.swagger.annotations.ApiModel;
  import io.swagger.annotations.ApiModelProperty;
  
  @ApiModel(description = "用户对象")
  public class User {
      @ApiModelProperty(value = "用户ID", required = true)
      private Long id;
  
      @ApiModelProperty(value = "用户名称")
      private String name;
  }
  

3. @ApiModelProperty

• 描述：用于描述模型属性的注释。
• 用法：

  @ApiModelProperty(value = "用户年龄", required = true)
  private Integer age;
  

其他常用注释

• @ApiTags：用于对多个 API 进行分类。
• @ApiIgnore：用于忽略某个 API，不在文档中显示。

总结

使用 Swagger 和 Knif4j 注释可以清晰地描述 API 的功能、参数和返回值，使得生成的文档更加易于理解和使用。通过合理使用这些注释，可以有效提升 API 的可维护性和可读性。

原文地址：https://blog.csdn.net/ckk1314520/article/details/142797707

免责声明：本站文章内容转载自网络资源，如本站内容侵犯了原著者的合法权益，可联系本站删除。更多内容请关注自学内容网（zxcms.com）！