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

Question

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

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

请求正文：

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

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

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 我已经向最终用户展示了如何替换用户名。大摇大摆，请求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

一种方法可以创建多个响应示例是可能的return，但是对于一个响应代码只能创建一个示例是可能的。

@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，作为响应，将 return 完整地提供有关特定方法可以做什么以及 request/response 将是什么的完整信息。在这里你有更好的解释：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);

希望这就是您要找的。

Answer 2

我在模式的帮助下在入口点添加了示例

@Parameter(description = "Update User", required = true, schema = @Schema (example = "{\n  "
                    + "\"operationList\": [\n    "
                    + "{\n      \"op\": \"replace\",\n      \"path\": \"/username\",\n      \"value\": \"john1991\"\n    },\n    "
                    + "{\n      \"op\": \"replace\",\n      \"path\": \"/description\",\n      \"value\": \"NewDescription\"\n    },\n    "
                    + "{\n      \"op\": \"add\",\n      \"path\": \"/memberships\",\n      "
                    + "\"value\":[\"1234\",\"6789\"]\n    "
                    + "{\n      \"op\": \"remove\",\n      \"path\": \"/privileges\",\n      \"value\":[\"148\",\"155\"]\n    "
                    + "}\n  ]\n}")) @Valid PatchOperations<UserPatchOperation> operationList) throws RestException

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

How to show multiple example in swagger documentation?

java

rest

swagger

swagger-2.0