Springfox迁移到 Springdoc OpenAPI 3

将项目从 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 等

迁移时，主要是将 Springfox 中的注解替换为 Springdoc 中对应的注解，并根据 OpenAPI 3 的规范调整 API 文档描述。