Swagger 3 注解使用指南

程序员杰瑞

24404人浏览 · 2023-06-07 09:49:48

程序员杰瑞 · 2023-06-07 09:49:48 发布

1. 基本信息注解

@OpenAPIDefinition

描述：用于定义整个 API 文档的基本信息。
可用于：类、接口。
属性：
- info：指定 @Info 注解的对象，用于描述 API 文档的基本信息。

@Info

描述：用于定义 API 文档的基本信息。
可用于：类、接口。
属性：
- title：API 的标题。
- description：API 的描述。
- version：API 的版本号。
- termsOfService：服务条款的 URL。
- contact：指定 @Contact 注解的对象，用于描述联系人信息。
- license：指定 @License 注解的对象，用于描述许可证信息。

@Contact

描述：用于定义 API 文档中的联系人信息。
可用于：类、接口。
属性：
- name：联系人的名称。
- url：联系人的网址。
- email：联系人的电子邮件地址。

@License

描述：用于定义 API 文档中的许可证信息。
可用于：类、接口。
属性：
- name：许可证的名称。
- url：许可证的网址。

2. 分组注解

@Tag

描述：用于给 API 分组，用途类似于为 API 文档添加标签。
可用于：方法、类、接口。
属性：
- name：分组的名称。

3. 请求方法注解

以下注解用于描述 API 的请求方法：

@Operation

描述：用于描述 API 的操作。
可用于：方法。
属性：
- summary：操作的摘要信息。
- description：操作的详细描述。
- tags：指定 @Tag 注解的对象数组，用于将操作归类到特定的分组。
- parameters：指定 @Parameter 注解的对象数组，用于描述操作的输入参数。
- responses：指定 @ApiResponse 注解的对象数组，用于描述操作的响应结果。
- requestBody：指定 @RequestBody 注解的对象，用于描述操作的请求体。

@Parameter

描述：用于描述操作的输入参数。
可用于：方法。
属性：
- name：参数的名称。
- in：参数的位置，可以是 path、query、header、cookie 中的一种。
- description：参数的描述。
- required：参数是否必需，默认为 false。
schema：指定 @Schema 注解的对象，用于描述参数的数据类型。

@RequestBody

描述：用于描述操作的请求体。
可用于：方法。
属性：
- required：请求体是否必需，默认为 false。
- content：指定 @Content 注解的对象数组，用于描述请求体的内容。

@ApiResponse

描述：用于描述操作的响应结果。
可用于：方法。
属性：
- responseCode：响应的状态码。
- description：响应的描述。
- content：指定 @Content 注解的对象数组，用于描述响应的内容。

@Content

描述：用于描述请求体或响应的内容。
可用于：方法。
属性：
- mediaType：内容的媒体类型。
- schema：指定 @Schema 注解的对象，用于描述内容的数据类型。

@Schema

描述：用于描述数据模型的属性。
可用于：方法、类、接口。
属性：
- title：数据模型的标题。
- description：数据模型的描述。
- type：数据模型的类型。
- format：数据模型的格式。

4. 路径注解

以下注解用于描述 API 的路径：

@Path

描述：用于定义路径参数。
可用于：方法。
属性：
- value：路径参数的名称。

@PathVariable

描述：用于描述路径参数。
可用于：方法的参数。
属性：
- value：路径参数的名称。

@RequestParam

描述：用于描述查询参数。
可用于：方法的参数。
属性：
- value：查询参数的名称。
- required：查询参数是否必需，默认为 false。

@RequestBody

描述：用于描述请求体。
可用于：方法的参数。

5. 响应注解

以下注解用于描述 API 的响应结果：

@ApiResponse

描述：用于描述响应结果。
可用于：方法。
属性：
- responseCode：响应的状态码。
- description：响应的描述。
- content：指定 @Content 注解的对象数组，用于描述响应的内容。

@Content

描述：用于描述响应结果的内容。
可用于：方法。
属性：
- mediaType：内容的媒体类型。
- schema：指定 @Schema 注解的对象，用于描述内容的数据类型。

@Schema

描述：用于描述数据模型的属性。
可用于：方法、类、接口。
属性：
- title：数据模型的标题。
- description：数据模型的描述。
- type：数据模型的类型。
- format：数据模型的格式。

6.使用示例

当使用Swagger 3注解编写API文档时，以下是一个示例代码，演示了如何使用各种注解来描述API的信息、请求参数和响应结果：

@RestController
@RequestMapping("/api/users")
@Tag(name = "用户管理", description = "用于管理用户信息")
public class UserController {

    @Autowired
    private UserService userService;

    @GetMapping("/{id}")
    @Operation(summary = "根据ID获取用户信息", description = "根据用户ID查询用户的详细信息")
    @ApiResponse(responseCode = "200", description = "成功获取用户信息")
    @ApiResponse(responseCode = "404", description = "未找到对应用户")
    public ResponseEntity<User> getUserById(@PathVariable("id") Long id) {
        User user = userService.getUserById(id);
        if (user != null) {
            return ResponseEntity.ok(user);
        } else {
            return ResponseEntity.notFound().build();
        }
    }

    @PostMapping
    @Operation(summary = "创建用户", description = "创建新用户")
    @ApiResponse(responseCode = "201", description = "成功创建用户")
    public ResponseEntity<User> createUser(@RequestBody CreateUserRequest request) {
        User user = userService.createUser(request);
        return ResponseEntity.status(HttpStatus.CREATED).body(user);
    }

    @PutMapping("/{id}")
    @Operation(summary = "更新用户信息", description = "根据用户ID更新用户的信息")
    @ApiResponse(responseCode = "200", description = "成功更新用户信息")
    @ApiResponse(responseCode = "404", description = "未找到对应用户")
    public ResponseEntity<User> updateUser(@PathVariable("id") Long id, @RequestBody UpdateUserRequest request) {
        User user = userService.updateUser(id, request);
        if (user != null) {
            return ResponseEntity.ok(user);
        } else {
            return ResponseEntity.notFound().build();
        }
    }

    @DeleteMapping("/{id}")
    @Operation(summary = "删除用户", description = "根据用户ID删除用户")
    @ApiResponse(responseCode = "204", description = "成功删除用户")
    @ApiResponse(responseCode = "404", description = "未找到对应用户")
    public ResponseEntity<Void> deleteUser(@PathVariable("id") Long id) {
        boolean deleted = userService.deleteUser(id);
        if (deleted) {
            return ResponseEntity.noContent().build();
        } else {
            return ResponseEntity.notFound().build();
        }
    }
}

在上述示例中，我们使用了@Tag注解来分组API，@Operation注解来描述每个API操作的摘要和详细描述，@ApiResponse注解来描述响应结果，@PathVariable注解来描述路径参数，@RequestBody注解来描述请求体，以及@ApiResponse和@ApiResponse注解来描述响应结果。

阅读全文

AI总结