openapi - 如何在示例代码部分显示错误代码描述？

Question

我在主要部分中显示了错误代码描述：

但我还想在此处的示例部分中显示这些代码描述：

我在示例部分看到了一些可以生成这些描述的 API 文档：

我怎么能做这样的事情？

PS：请注意，我正在使用 springdoc 公开开放 API 规范。

Answer 1

一种方法是您可以定义一个字符串作为示例@ApiResponse

您可以通过两种方式实现此目的

1.定义您的错误消息格式类，或者您可以使用内置（如果有）

public class ExceptionResponse {

    private Instant time;
    private int status;
    private String error;
    private String exception;
    private String message;
}

然后定义您的自定义消息字符串，如下所示。

public static final String exampleInternalError = "{\r\n" + "  \"status\": 500,\r\n" + "\"error\": Bad Request,\r\n"
            + "  \"message\": \"Your custome message goes here\"\r\n" + "}";

同样用于将示例显示为

@ApiResponse(responseCode = "400", description = "Bad Request", 
                  content = @Content(schema = @Schema(implementation = ExceptionResponse .class), 
                        examples = @ExampleObject(description = "Bad Request", value = exampleInternalError)))

这将大摇大摆地显示为

2.如果您不想使用上述格式，那么您可以简单地使用

如下所述

@ApiResponse(responseCode = "400", description = "Bad Request", 
content = @Content(schema = @Schema(implementation = String.class), 
              examples = @ExampleObject(description = "Bad Request", value = "\"Your details about error code and error message goes here")))

这将大摇大摆地显示为