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

Question

在我的REST API补丁操作中，我使用的是v3swagger-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() {
    }
}

{
  "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();

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

请记住，大摇大摆的文档应该以一种有人能够连接到您的api并执行某些操作的方式进行。您不需要在那里提供太多的响应。这是用于rest方法的选项。OPTIONS方法基本上是一个GET，它不需要任何参数，响应时将返回关于某个方法可以做什么以及请求/响应是什么的完整信息。这里有更好的解释：RESTful API方法；头和选项

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

我希望那就是你要找的。