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

Question

在我的 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带有这个例子。

除了通过这个补丁操作的用户名，最终用户可以更新描述然后路径将是/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 方法添加多个示例吗？谢谢。

Answer 1

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

@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);

我希望这就是您要找的。