thinkphp 显示第三方网站图片,民权做网站,做买鞋网站的论文,上海服饰网站建设将项目从 Springfox 迁移到 Springdoc OpenAPI 3 时#xff0c;主要的工作是将原先使用的 Springfox 注解替换为 Springdoc OpenAPI 3 中的对应注解。虽然 Springdoc OpenAPI 3 基于 OpenAPI 3 规范#xff0c;并且有一些不同的命名方式和设计理念#xff0c;但大部分注解的…将项目从 Springfox 迁移到 Springdoc OpenAPI 3 时主要的工作是将原先使用的 Springfox 注解替换为 Springdoc OpenAPI 3 中的对应注解。虽然 Springdoc OpenAPI 3 基于 OpenAPI 3 规范并且有一些不同的命名方式和设计理念但大部分注解的功能是类似的。
主要注解对比表
功能/注解Springfox 注解Springdoc OpenAPI 3 注解接口文档描述ApiOperationOperation接口文档描述错误响应等ApiResponsesApiResponses接口文档描述单个响应ApiResponseApiResponse接口参数描述ApiParamParameter请求模型描述ApiModelSchema响应模型描述ApiModelPropertySchema类/接口文档描述ApiTag全局文档描述ApiOperation、ApiResponsesOpenAPIDefinition请求头描述ApiImplicitParamRequestHeader 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 ResponseEntityUser 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 ResponseEntityUser getUser(PathVariable Long id) {return ResponseEntity.ok(userService.getUserById(id));
}4. ApiParam → Parameter
在 Springfox 中ApiParam 用于描述方法参数。在 Springdoc 中使用 Parameter 来描述。
Springfox 示例:
GetMapping(/users)
public ListUser getUsers(ApiParam(value 分页参数, required true) RequestParam int page) {return userService.getUsers(page);
}Springdoc 示例:
GetMapping(/users)
public ListUser 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 注解ApiOperationOperationApiResponsesApiResponsesApiResponseApiResponseApiParamParameterApiModelSchemaApiModelPropertySchemaApiTagApiImplicitParamRequestParam、RequestHeader 等
迁移时主要是将 Springfox 中的注解替换为 Springdoc 中对应的注解并根据 OpenAPI 3 的规范调整 API 文档描述。
