gpt4 book ai didi

java - 如何在 swagger 文档中显示多个示例?

转载 作者:行者123 更新时间:2023-12-05 04:58:48 68 4
gpt4 key购买 nike

在我的 REST API PATCH 操作中,我使用的是 v3 swagger-annotation:2.0.6

我试图为我的补丁操作 PATCH/users/id 添加更多示例作为 swagger 模式。

请求正文:

{
"operationList": [
{
"op": "replace",
"path": "/username",
"value": "john1991"
}
]
}

目前我有以下请求模型类。

public class UserPatchOp extends PatchOperation {
@Override
@Schema(description = "some description", example = "replace", required = true)
public PatchOperator getOp() {
return super.getOp();
}

@Override
@Schema(description = "some description", example = "/username", required = true)
public String getPath() {
return super.getPath();
}

@Override
@Schema(description = "some description", , example = "john1991", required = true)
public Object getValue() {
return super.getValue();
}
}

在 PatchOperation.java 中

public class PatchOperation {

/**
* {@link PatchOperator} operation to be performed
*/
@Schema(description = "Operation to be performed", required = true)
@JsonProperty
@NotNull
private PatchOperator op;

@Schema(description = "Path to target where operation will be performed", required = true)
@JsonProperty
@Pattern(regexp = "/([/A-Za-z0-9~])*-*", message = "Invalid path. Please follow regex pattern")
private String path;

@Schema(description = "Value used by operation")
@JsonProperty
private Object value;

public PatchOperation() {
}
}

在 swagger 文档中,在 UserPatchOp.java 中,我向最终用户展示了如何替换用户名。 Swagger ,请求bogy带有这个例子。

enter image description here

除了通过这个补丁操作的用户名,最终用户可以更新描述然后路径将是/description

最终用户还可以更新它所属的用户组 '/usergroups'所以总的来说,我想以同样的方式向 swagger 模式添加更多示例。但我做不到。因为我一次只能展示一个例子。

我想在 swagger 页面上向客户端显示以下多个操作。

{
"operationList": [
{
"op": "replace",
"path": "/username",
"value": "john1991"
},
{
"op": "remove",
"path": "/description"
},
{
"op": "add",
"path": "/memberships"
"value":["1224","8907"]
}
]
}

入口点方法是

@补丁

@Path("users/{id}")
@Consumes({MediaType.APPLICATION_JSON, APPLICATION_JSON_PATCH_JSON})
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = MessageConstants.OK, content = @Content(schema = @Schema(implementation = UserInfo.class))),
@ApiResponse(responseCode = "500", description = MessageConstants.SERVER_ERROR, content = @Content(schema = @Schema(implementation = RestError.class))),
@ApiResponse(responseCode = "400", description = MessageConstants.BAD_REQUEST, content = @Content(schema = @Schema(implementation = RestError.class))),
@ApiResponse(responseCode = "401", description = MessageConstants.UNAUTHORIZED, content = @Content(schema = @Schema(implementation = RestError.class))),
@ApiResponse(responseCode = "404", description = MessageConstants.NOT_FOUND, content = @Content(schema = @Schema(implementation = RestError.class)))})
public Response updatePartialUser(
@Parameter(description = "User Id", required = true) @PathParam("id") String id,
@Parameter(description = "User Update Info", required = true) @Valid PatchOperations<UserPatchOperation> operationList) {

有什么办法可以为 getOP、getPath 和 getValue 方法添加多个示例吗?谢谢。

最佳答案

可以创建一个方法可以返回的多个响应示例,但也可以只为一个响应代码执行一个示例。

@Operation(description = "Retrieves status of application",
responses = {
@ApiResponse(responseCode = "200",
description = "Everything works fine.",
content = @Content(mediaType = "application/json",
examples = @ExampleObject(value = "{\n" +
" \"success\" : true,\n" +
" \"message\" : \"OK\"\n" +
"}"))),
@ApiResponse(responseCode = "500",
description = "Application not working properly",
content = @Content(mediaType = "application/json",
examples = @ExampleObject(value = "{\n" +
" \"success\" : false,\n" +
" \"message\" : \"Application not working properly\"\n" +
"}")))
})
@GetMapping("haproxy")
ResponseEntity<BaseResponse> getHaProxy();

我不确定这是否是您想要的,但我看不到其他方式。

请记住,swagger 文档的编写方式应该使某人能够连接到您的 api 并执行一些操作。你不需要在那里提供太多的回应。那是针对 OPTIONS 的 rest 方法。 OPTIONS 方法基本上是一个不需要任何参数的 GET,作为响应将返回有关特定方法可以做什么以及请求/响应是什么的完整信息。在这里你有更好的解释:RESTful API methods; HEAD & OPTIONS

顺便说一句。你应该更新你的依赖项,swagger-annotations 现在是 2.1.4,2.0.6 是 2 年前的

编辑 2020-09-30 关于请求的正文:

可以像这样添加多个请求示例:

@Operation(description = "Creates a User",
requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody(description = "Request examples",
content = @Content(examples = {
@ExampleObject(name = "doing weird stuff", value = "http://localhost:7080"),
@ExampleObject(name = "doing weirdest stuff", value = "{\n\"test\":\"12\"\n}"),
})),
responses = {
@ApiResponse(responseCode = "200",
description = "Everything works fine.",
content = @Content(mediaType = "application/json",
schema = @Schema(implementation = UserResponse.class))),
@ApiResponse(responseCode = "404",
description = "Not found",
content = @Content(mediaType = "application/json",
examples = @ExampleObject(value = "{\"success\":false,\"message\":\"That shop or API version is not accessible yet\",\"httpStatus\":\"NOT_FOUND\"}"))),
@ApiResponse(responseCode = "500",
description = "Something went wrong",
content = @Content(mediaType = "application/json",
schema = @Schema(implementation = SomeBasicResponse.class)))
})
@Parameters({
@Parameter(in = ParameterIn.HEADER, name = "url",
content = @Content(schema = @Schema(type = "string", defaultValue = "localhost:7080")))
})

@PostMapping
ResponseEntity<UserResponse> createUser(@RequestHeader(name = "login", required = false) String login,
@RequestHeader(name = "password") String password,
@RequestBody UserRequest request);

RequestBody example No. 1

RequestBody example No. 2

我希望这就是您要找的。

关于java - 如何在 swagger 文档中显示多个示例?,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/63836654/

68 4 0
Copyright 2021 - 2024 cfsdn All Rights Reserved 蜀ICP备2022000587号
广告合作:1813099741@qq.com 6ren.com