Springfox迁移到 Springdoc OpenAPI 3

news2024/11/30 9:06:03

将项目从 Springfox 迁移到 Springdoc OpenAPI 3 时，主要的工作是将原先使用的 Springfox 注解替换为 Springdoc OpenAPI 3 中的对应注解。虽然 Springdoc OpenAPI 3 基于 OpenAPI 3 规范，并且有一些不同的命名方式和设计理念，但大部分注解的功能是类似的。

主要注解对比表

功能/注解	Springfox 注解	Springdoc OpenAPI 3 注解
接口文档描述	`@ApiOperation`	`@Operation`
接口文档描述（错误响应等）	`@ApiResponses`	`@ApiResponses`
接口文档描述（单个响应）	`@ApiResponse`	`@ApiResponse`
接口参数描述	`@ApiParam`	`@Parameter`
请求模型描述	`@ApiModel`	`@Schema`
响应模型描述	`@ApiModelProperty`	`@Schema`
类/接口文档描述	`@Api`	`@Tag`
全局文档描述	`@ApiOperation`、`@ApiResponses`	`@OpenAPIDefinition`
请求头描述	`@ApiImplicitParam`	`@RequestHeader`

Springfox 到 Springdoc 的主要迁移步骤与注解对比

1. `@ApiOperation` → `@Operation`

在 Springfox 中，@ApiOperation 用于描述 RESTful 接口的功能。Springdoc 使用 @Operation 代替。

Springfox 示例:

@ApiOperation(value = "获取用户信息", notes = "通过用户ID获取详细信息")
@GetMapping("/users/{id}")
public User getUser(@PathVariable Long id) {
    return userService.getUserById(id);
}

Springdoc 示例:

@Operation(summary = "获取用户信息", description = "通过用户ID获取详细信息")
@GetMapping("/users/{id}")
public User getUser(@PathVariable Long id) {
    return userService.getUserById(id);
}

2. `@ApiResponses` → `@ApiResponses`

@ApiResponses 在 Springfox 和 Springdoc 中的功能是相同的，用来描述接口的多个响应状态和返回类型。

Springfox 示例:

@ApiResponses({
    @ApiResponse(code = 200, message = "成功", response = User.class),
    @ApiResponse(code = 404, message = "用户未找到")
})
@GetMapping("/users/{id}")
public User getUser(@PathVariable Long id) {
    return userService.getUserById(id);
}

Springdoc 示例:

@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "成功", content = @Content(mediaType = "application/json", schema = @Schema(implementation = User.class))),
    @ApiResponse(responseCode = "404", description = "用户未找到")
})
@GetMapping("/users/{id}")
public User getUser(@PathVariable Long id) {
    return userService.getUserById(id);
}

3. `@ApiResponse` → `@ApiResponse`

描述单个响应状态的注解在 Springfox 和 Springdoc 中是一致的。@ApiResponse 用于指定响应的代码、描述和返回的类型。

Springfox 示例:

@ApiResponse(code = 200, message = "成功", response = User.class)
public ResponseEntity<User> getUser(@PathVariable Long id) {
    return ResponseEntity.ok(userService.getUserById(id));
}

Springdoc 示例:

@ApiResponse(responseCode = "200", description = "成功", content = @Content(mediaType = "application/json", schema = @Schema(implementation = User.class)))
public ResponseEntity<User> getUser(@PathVariable Long id) {
    return ResponseEntity.ok(userService.getUserById(id));
}

4. `@ApiParam` → `@Parameter`

在 Springfox 中，@ApiParam 用于描述方法参数。在 Springdoc 中，使用 @Parameter 来描述。

Springfox 示例:

@GetMapping("/users")
public List<User> getUsers(@ApiParam(value = "分页参数", required = true) @RequestParam int page) {
    return userService.getUsers(page);
}

Springdoc 示例:

@GetMapping("/users")
public List<User> getUsers(@Parameter(description = "分页参数", required = true) @RequestParam int page) {
    return userService.getUsers(page);
}

5. `@ApiModel` 和 `@ApiModelProperty` → `@Schema`

Springfox 使用 @ApiModel 和 @ApiModelProperty 来描述请求体和响应体的模型属性。而在 Springdoc 中，这些都通过 @Schema 注解来完成。

Springfox 示例:

@ApiModel(description = "用户对象")
public class User {
    @ApiModelProperty(notes = "用户ID", required = true)
    private Long id;

    @ApiModelProperty(notes = "用户名", required = true)
    private String name;
}

Springdoc 示例:

@Schema(description = "用户对象")
public class User {
    @Schema(description = "用户ID", required = true)
    private Long id;

    @Schema(description = "用户名", required = true)
    private String name;
}

6. `@Api` → `@Tag`

@Api 用于描述整个类的 API 元信息。在 Springdoc 中，使用 @Tag 来替代它。

Springfox 示例:

@Api(tags = "用户管理 API")
@RestController
@RequestMapping("/users")
public class UserController {
    // Controller methods
}

Springdoc 示例:

@Tag(name = "用户管理 API")
@RestController
@RequestMapping("/users")
public class UserController {
    // Controller methods
}

7. `@ApiImplicitParam` → `@RequestParam`、`@RequestHeader`、`@PathVariable` 等

在 Springfox 中，@ApiImplicitParam 用于声明请求参数的元信息。在 Springdoc 中，这些信息通过 @RequestParam、@RequestHeader 和 @PathVariable 等注解直接在参数上描述。

Springfox 示例:

@ApiImplicitParam(name = "Authorization", value = "JWT token", required = true, paramType = "header")
@GetMapping("/profile")
public User getProfile(@RequestHeader("Authorization") String token) {
    return userService.getProfile(token);
}

Springdoc 示例:

@GetMapping("/profile")
public User getProfile(@RequestHeader(description = "JWT token", required = true) String token) {
    return userService.getProfile(token);
}

总结

Springdoc OpenAPI 3 中的注解与 Springfox 大致相同，主要的变化在于命名方式。以下是迁移时的关键对比：

Springfox 注解	Springdoc 注解
`@ApiOperation`	`@Operation`
`@ApiResponses`	`@ApiResponses`
`@ApiResponse`	`@ApiResponse`
`@ApiParam`	`@Parameter`
`@ApiModel`	`@Schema`
`@ApiModelProperty`	`@Schema`
`@Api`	`@Tag`
`@ApiImplicitParam`	`@RequestParam`、`@RequestHeader` 等