16个Swagger工具注解：Swagger架构分析与注解使用案例(必须收藏)

Swagger（现在通常指的是 OpenAPI Specification，简称 OAS），是一个用于生成、描述、调用和可视化 RESTful Web 服务的框架。Swagger 的核心功能之一是使用注解来描述 API，这些注解可以直接嵌入到你的代码中，通常是 Java 或其他支持的编程语言。这些注解帮助自动化 API 文档的生成过程，并提供 API 的详细描述。

Swagger 注解介绍

Swagger 提供了一系列注解，用于描述 API 的不同方面，包括路径、参数、响应等。以下是一些常用的 Swagger 注解：

1. @Api: 用于描述整个 API 或控制器的元数据，如授权、标题和描述。
2. @ApiOperation: 描述一个 API 操作，提供关于操作的详细信息，如摘要、描述和值。
3. @ApiResponse: 描述一个特定的响应类型，包括响应代码和描述。
4. @ApiResponses: 包含多个 @ApiResponse 注解，用于描述一个操作可能产生的多种响应。
5. @ApiParam: 描述一个 API 操作的参数，包括参数的名称、描述、是否必须等。
6. @ApiModel: 用于描述一个数据模型，通常用于请求和响应体。
7. @ApiModelProperty: 描述模型中的一个属性，提供关于属性的额外信息，如描述、数据类型和访问权限。
8. @ApiImplicitParam: 用于描述请求体中的一个参数，特别是对于复杂类型的参数。
9. @ApiImplicitParams: 包含多个 @ApiImplicitParam 注解，用于描述多个请求体参数。
10. @ApiIgnore: 用于忽略某个方法或类，不将其包含在生成的 API 文档中。
11. @ApiProperty: 用于描述模型属性的元数据，如访问级别、数据类型和描述。
12. @Authorization: 描述与 API 操作相关的安全授权信息。
13. @AuthorizationScope: 描述具体的授权范围，通常与 OAuth2 安全方案一起使用。
14. @SecurityDefinition: 描述 API 的安全定义，如 API 密钥、OAuth2 等。
15. @SwaggerDefinition: 用于定义 Swagger 的配置信息，如信息、版本、授权方式等。

肖哥弹架构 跟大家“弹弹” 框架注解使用，需要代码关注

欢迎 点赞，关注，评论。

关注公号Solomon肖哥弹架构获取更多精彩内容

历史热点文章

• 28个验证注解，通过业务案例让你精通Java数据校验(收藏篇)
• Java 8函数式编程全攻略：43种函数式业务代码实战案例解析(收藏版)
• 69 个Spring mvc 全部注解：真实业务使用案例说明(必须收藏)
• 24 个Spring bean 全部注解：真实业务使用案例说明(必须收藏)
• MySQL索引完全手册：真实业务图文讲解17种索引运用技巧(必须收藏)
• 一个项目代码讲清楚DO/PO/BO/AO/E/DTO/DAO/ POJO/VO

Swagger 架构设计图

架构组件解释：

1. 开发者：编写 API 接口的代码，并使用 Swagger 注解来描述这些接口。
2. Swagger 注解：注解被嵌入到代码中，用于描述 API 的各种特性，如路径、参数、响应等。
3. Java/Python/其他语言：Swagger 支持多种编程语言，注解被嵌入到相应的语言代码中。
4. API 服务器：编译后的代码部署到服务器上，提供 API 服务。
5. Swagger Core：Swagger 的核心库，负责解析注解和处理 API 请求。
6. API 文档：由 Swagger Core 生成的文档，描述了 API 的详细信息。
7. Swagger UI：一个用于展示 API 文档的网页界面，允许用户浏览文档并测试 API。

1. 类和方法描述

1.1 @Api

• 注解作用介绍

用于描述整个类级别的详细信息，通常用于控制器类。

• 注解属性介绍
  • value: 提供类描述。
  • tags: 分组标签。
• 注解业务案例

@Api(tags = "用户管理", description = "管理用户相关操作")
public class UserController {
    // 类内容
}

• 注解使用效果： 使用 @Api 后，Swagger 会将 UserController 类识别为属于 “用户管理” 分组，并提供描述信息。

1.2 @ApiOperation

• 注解作用介绍

描述一个方法的操作，提供关于 API 操作的详细信息。

• 注解属性介绍
  • value: 操作的简短描述。
  • notes: 详细描述。
• 注解业务案例

@ApiOperation(value = "获取用户列表", notes = "获取所有用户的详细信息")
public List<User> getAllUsers() {
    // 方法实现
}

• 注解使用效果： 使用 @ApiOperation 后，Swagger 文档会显示 getAllUsers 方法的摘要和详细描述。

2. 参数描述

2.1 @ApiParam

• 注解作用介绍

描述方法参数的详细信息。

• 注解属性介绍
  • name: 参数名称。
  • value: 参数描述。
  • required: 是否必须。
• 注解业务案例

public User getUserById(@ApiParam("用户ID") @PathVariable Long id) {
    // 方法实现
}

• 注解使用效果 使用 @ApiParam 后，Swagger 文档会详细描述 getUserById 方法的参数。

2.2 @ApiImplicitParam / @ApiImplicitParams

• 注解作用介绍

用于描述请求参数的详细信息，特别是对于复杂类型的请求参数。

• 注解业务案例

@ApiOperation("创建用户")
@PostMapping("/users")
@ApiImplicitParam(name = "user", value = "用户详细信息", required = true, dataType = "User")
public User createUser(@RequestBody User user) {
    // 方法实现
}

• 注解使用效果： 使用 @ApiImplicitParam 后，Swagger 文档会详细描述 createUser 方法的请求体参数。

3. 响应描述

3.1 @ApiResponse

• 注解作用介绍

描述一个 API 响应的详细信息。

• 注解属性介绍
  • code: 响应码。
  • message: 响应消息。
• 注解业务案例

@ApiResponse(code = 200, message = "成功获取用户信息")

• 注解使用效果： 使用 @ApiResponse 后，Swagger 文档会显示对应操作的一个预期响应。

3.2 @ApiResponses

• 注解作用介绍

描述多个 API 响应的详细信息。

• 注解业务案例

@ApiResponses({
    @ApiResponse(code = 200, message = "成功"),
    @ApiResponse(code = 404, message = "用户未找到")
})

• 注解使用效果： 使用 @ApiResponses 后，Swagger 文档会显示对应操作的所有预期响应。

4. 模型描述

4.1 @ApiModel

• 注解作用介绍

用于描述一个模型类，提供模型的元数据。

• 注解业务案例

@ApiModel(description = "用户信息模型")
public class User {
    // 类内容
}

• 注解使用效果 使用 @ApiModel 后，Swagger 文档会为 User 类提供描述。

4.2 @ApiModelProperty

• 注解作用介绍

用于描述模型属性的详细信息。

• 注解业务案例

@ApiModel
public class User {
    @ApiModelProperty(value = "用户姓名", required = true)
    private String name;
}

• 注解使用效果： 使用 @ApiModelProperty 后，Swagger 文档会为 User 类的 name 属性提供详细描述。

5. 安全和授权

5.1 @SecurityDefinition / @SecurityDefinitions

• 注解作用介绍

描述 API 的安全定义。

• 注解业务案例

@SwaggerDefinition(
    securityDefinitions = @SecurityDefinition(
        key = "oauth2", 
        type = "oauth2", 
        scopes = {
            @AuthorizationScope(scope = "read", description = "读取权限")
        }
    )
)

• 注解使用效果： 使用 @SecurityDefinition 后，Swagger 文档会包含安全方案的定义。

6. 文档控制

6.1 @ApiIgnore

• 注解作用介绍

用于忽略某个方法或类，不将其包含在 Swagger 文档中。

• 注解业务案例

@ApiIgnore
public void internalMethod() {
    // 方法实现
}

• 注解使用效果： 使用 @ApiIgnore 后，internalMethod 方法不会出现在 Swagger 文档中。

7. 已废弃的注解

7.1 @Authorization / @AuthorizationScope

• 注解作用介绍

描述 API 的安全授权信息（已废弃，建议使用 @SecurityRequirement）。

• 注解业务案例

@ApiOperation("获取受保护的资源")
@Api(authorizations = @Authorization(value = "oauth2", scopes = {
    @AuthorizationScope(scope = "read", description = "读取权限"),
    @AuthorizationScope(scope = "write", description = "写入权限")
}))
@GetMapping("/protected")
public ResponseEntity<String> getProtectedResource() {
    // 方法实现
}

• 注解使用效果： 使用 @Authorization 和 @AuthorizationScope 后，Swagger 会将 getProtectedResource 方法标记为需要特定的授权范围。

8. 分组

8.1 @Tag

• 注解作用介绍

用于对 API 进行分组。

• 注解业务案例

@SwaggerDefinition(tags = @Tag(name = "用户管理", description = "用户相关的操作"))

• 注解使用效果: 使用 @Tag 后，Swagger 会将相关的 API 分组到 “用户管理” 标签下。

9. Swagger综合案例

用户管理系统的 REST API，包括用户信息的增删改查功能。

@Api(tags = "用户管理", description = "用户管理相关的操作")
@RestController
@RequestMapping("/api/users")
public class UserController {

    private final UserService userService;

    @Autowired
    public UserController(UserService userService) {
        this.userService = userService;
    }

    @ApiOperation(value = "获取用户列表", notes = "获取系统中所有用户的列表")
    @ApiResponses(value = {
        @ApiResponse(code = 200, message = "成功获取用户列表"),
        @ApiResponse(code = 500, message = "服务器内部错误")
    })
    @GetMapping
    public List<User> getAllUsers() {
        return userService.findAll();
    }

    @ApiOperation(value = "创建新用户", notes = "创建一个新的用户")
    @ApiResponses(value = {
        @ApiResponse(code = 201, message = "用户创建成功"),
        @ApiResponse(code = 400, message = "用户创建失败")
    })
    @PostMapping
    @ApiImplicitParam(name = "user", value = "用户详细实体", required = true, dataType = "User")
    public User createUser(@RequestBody User user) {
        return userService.save(user);
    }

    @ApiOperation(value = "获取单个用户信息", notes = "根据用户ID获取单个用户信息")
    @ApiResponses(value = {
        @ApiResponse(code = 200, message = "成功获取用户信息"),
        @ApiResponse(code = 404, message = "用户未找到")
    })
    @GetMapping("/{id}")
    public User getUserById(@PathVariable Long id) {
        return userService.findById(id);
    }

    @ApiOperation(value = "更新用户信息", notes = "根据用户ID更新用户信息")
    @ApiResponses(value = {
        @ApiResponse(code = 200, message = "用户信息更新成功"),
        @ApiResponse(code = 404, message = "用户未找到")
    })
    @PutMapping("/{id}")
    public User updateUser(@PathVariable Long id, @RequestBody User user) {
        user.setId(id);
        return userService.save(user);
    }

    @ApiOperation(value = "删除用户", notes = "根据用户ID删除用户")
    @ApiResponses(value = {
        @ApiResponse(code = 200, message = "用户删除成功"),
        @ApiResponse(code = 404, message = "用户未找到")
    })
    @DeleteMapping("/{id}")
    public String deleteUser(@PathVariable Long id) {
        userService.deleteById(id);
        return "User deleted successfully";
    }
}

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(description = "用户信息模型")
public class User {
    @ApiModelProperty(value = "用户的唯一标识符", readOnly = true)
    private Long id;

    @ApiModelProperty(value = "用户的名称", required = true)
    private String name;

    @ApiModelProperty(value = "用户的年龄")
    private Integer age;

    // Getters and Setters
    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }
}

public interface UserService {
    List<User> findAll();
    User save(User user);
    User findById(Long id);
    void deleteById(Long id);
}

说明

1. UserController：这是一个 REST 控制器，包含获取用户列表、创建新用户、获取单个用户、更新用户信息和删除用户的方法。
2. User：这是一个模型类，表示用户信息。
3. UserService：这是一个服务接口，定义了用户管理的基本操作。
   本案例展示了如何在实际的 Spring Boot 应用程序中使用 Swagger 注解来描述 REST API。每个方法都使用了 @ApiOperation 和 @ApiResponses 注解来描述操作和响应，而模型类 User 使用了 @ApiModel 和 @ApiModelProperty 注解来描述模型属性。