自学内容网 自学内容网
自学内容网 > 正文

Springfox迁移到 Springdoc OpenAPI 3

🕗 发布于 2024-11-30 18:48 swagger  springboot  

将项目从 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 文档描述。


原文地址：https://blog.csdn.net/a309220728/article/details/144141486

免责声明：本站文章内容转载自网络资源，如本站内容侵犯了原著者的合法权益，可联系本站删除。更多内容请关注自学内容网（zxcms.com）！

相关文章

自学内容网
Copyright © 2015-2025