Swagger工具集及Swagger工具集常见注解和用法

目录

一、什么是Swagger工具集

二、swagger常用的注解和用法

@Api

@ApiOperation

@ApiParam

@ApiModel

@ApiModelProperty

@ApiIgnore

三、常见问题

1.@ApiModelProperty和@ApiOperation有什么区别？

---

一、什么是Swagger工具集

Swagger工具集是一系列围绕OpenAPI Specification（OAS，原名为Swagger Specification）规范构建的工具，主要用于API的设计、文档生成、测试和部署。它允许开发人员通过标准和一致的方式定义RESTful API，并能自动化地生成交互式的API文档、SDKs（客户端代码）、服务器模拟（stubs）以及其他API相关的工件。

Swagger工具集包括但不限于以下几个核心组件：

• Swagger Editor：一个在线编辑器，用于创建和编辑符合OpenAPI规范的API定义文件（YAML或JSON格式），并实时预览文档。

• Swagger UI：一个静态网页应用，它可以读取OpenAPI规范定义文件，并将其呈现为交互式的API文档，其中包含了接口说明、请求参数、响应示例等功能，可以直接在界面上进行API的调用和测试。

• Swagger Codegen：可以根据OpenAPI规范生成多种编程语言的客户端和服务端代码，例如Java、Python、JavaScript等，大大加快了API的开发和集成速度。

• Swagger Core：一套Java库，提供了处理和解析OpenAPI规范的基础结构和模型。

在Spring Boot项目中集成Swagger后，可以通过使用对应的注解（如@Api, @ApiOperation, @ApiModelProperty等）来装饰控制器和模型类，从而自动生成详细的API文档。这样不仅提高了API文档的一致性和准确性，也极大地简化了开发流程，提升了前后端协作的效率。

二、swagger常用的注解和用法

Swagger（现在通常称为OpenAPI Specification，但仍有很多开发者习惯性地称其为Swagger）在Java生态中配合Spring框架或其他Web框架时，常用的一些注解可以帮助定义和文档化RESTful API。以下是Swagger/Swagger UI中一些常见的注解及其用法：

• @Api

  • 类级别的注解，用于标记一个类作为API资源。
  • 参数：
    • value: 可选，设置资源的名称或ID，会在文档中展示。
    • tags: 用于分类，方便在Swagger UI中组织和筛选不同的API分组。
    • description: 对该API资源的简短描述。

• @ApiOperation

  • 方法级别的注解，用于描述Controller中的HTTP方法（GET、POST等）的行为和用途。
  • 参数：
    • value: HTTP方法的简短描述。
    • notes: 更详细的操作说明。
    • tags: 同上，用于归类。
    • response: 可指定响应的类型。
    • httpMethod: 指定HTTP方法。

• @ApiParam

  • 用于方法参数或方法返回值上的注解，用于描述请求参数或响应字段。
  • 参数：
    • value: 参数的描述。
    • name: 参数名。
    • required: 表示该参数是否为必需。
    • dataType: 数据类型。
    • defaultValue: 默认值。
    • 其他还有allowableValues、example等参数，用于进一步约束和描述参数。

• @ApiModel

  • 类级别的注解，用于定义一个复杂的请求体或响应体模型。
  • 参数：
    • value: 模型的名称。
    • description: 模型的描述。

• @ApiModelProperty

  • 用于类属性上的注解，描述模型中的单个属性。
  • 参数：
    • value: 属性描述。
    • name: 属性名（默认情况下使用变量名）。
    • required: 表示该属性在模型中是否必须存在。
    • example: 示例值。

• @ApiIgnore

  用于方法或类级别，用于忽略某个API资源或方法，使其不被Swagger扫描和包含在生成的文档中。
• 示例用法：

@Api(value = "用户管理", description = "用户相关操作")
public class UserController {

    @ApiOperation(value = "获取用户信息", tags = "用户信息")
    @GetMapping("/{userId}")
    public User getUserInfo(@ApiParam(name = "userId", value = "用户ID", required = true) @PathVariable Long userId) {
        // ...
    }

    @ApiModel(description = "用户实体")
    public class User {
        @ApiModelProperty(value = "用户ID", example = "123")
        private Long id;
        // ...
    }
}

通过这些注解，开发者可以轻松地为他们的API编写结构化的、机器可读的文档，同时Swagger工具会基于这些注解生成丰富的API文档界面，便于API使用者理解和调用。

三、常见问题

1.@ApiModelProperty和@ApiOperation有什么区别？

答@ApiModelProperty 和 @ApiOperation 都是 Swagger 工具集中的注解，用于增强 RESTful API 的文档生成和交互体验，但它们的作用范围和目的略有不同。

• @ApiOperation：

  • 该注解用于类的方法级别，通常放在控制器（Controller）的方法前面，用于描述整个 HTTP 请求动作的信息，如请求路径、HTTP 方法（GET、POST 等）、操作的简短摘要、详细描述、响应的状态码、响应的实体类等。
  • 示例：

    @ApiOperation(value = "创建用户", notes = "用于新增一个用户", tags = {"用户管理"})
    @PostMapping("/users")
    public ResponseEntity<User> createUser(@RequestBody User user) {
        // ...
    }

• @ApiModelProperty：

  • 该注解用于类的字段级别或属性级别，用于描述类的属性或模型字段，出现在实体类（Model）中，为 API 文档提供关于请求或响应中字段的详细信息，如字段名、字段描述、是否必填、默认值等。
  • 示例：

    public class User {
    
        @ApiModelProperty(value = "用户名", required = true)
        private String username;
    
        @ApiModelProperty(value = "密码", required = true)
        private String password;
    
        // getters and setters...
    }

总之，@ApiOperation 主要用于描述一个完整的 HTTP 请求操作，而 @ApiModelProperty 专注于描述请求或响应中涉及的实体类字段信息。两者结合使用，可以为 Swagger 自动生成的 API 文档提供丰富的上下文和细节说明。