OpenApi 如何从资源文件添加示例 @RequestBody -> @Content -> @Schema -> 示例

Question

我正在开发一个基于服务的应用程序，为此我添加了基于的openapi注释，例如@RequestBody、@Parameter、@Schema，在@模式.我有一个示例字段，可以为其提供字符串格式的示例模板。

我已经提供了示例JSON字符串，但JSON内容非常丰富，因此我想从我的参考资料文件夹中的。但我目前无法加载它。有人能告诉我如何从文件而不是字符串中添加示例内容吗？

我试着查找，发现有一个字段＜code＞externalValue＜/code＞但我无法理解如何使其工作。以下是文档的链接。

下面是我的代码，它运行得非常好:

@Path("/generate")
@POST
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
@RequestBody(description = "InputTemplate body",
        content = @Content(schema = @Schema(implementation = InputTemplate.class, example = "{\n" +
                "  \"names\":[\n" +
                "    \"Batman\",\n" +
                "    \"Superman\",\n" +
                "    \"Ironman\"\n" +
                "  ],\n" +
                "  \"jobs\":[\n" +
                "    \"Fighting\",\n" +
                "    \"Fyling\",\n" +
                "    \"Teching\"\n" +
                "  ]\n" +
                "}")))
public Multi<String> generate(final Map<String, Object> input) throws CustomException {
        
}

我想用我的< code>resources文件夹中的外部文件的内容替换< code>example中的JSON内容。

在尝试了许多事情之后，我知道我需要使用< code>@ExampleObject，但是如果我添加了相应的注释并尝试打开我的< code>Swagger UI，那么我就不能获得我添加的文件的内容。相反，它为我提供了来自< code>InputTemplate.class的数据。

以下是修改后的代码：

@RequestBody(description = "InputTemplate body",
        content = @Content(schema = @Schema(implementation = InputTemplate.class), examples = {
                @ExampleObject(name = "Example-1",
                        description = "Example-1 for InputTemplate.",
                        ref = "#/resources/Example1.json"), externalValue = "#/resources/Example2.json"
                @ExampleObject(name = "Example-2",
                        description = "Example-2 for InputTemplate.",
                        ref = "#/resources/Example1.json") //externalValue = "#/resources/Example1.json"
        }))

我试图调查一个类似的问题，但提供的回答对我不起作用:

1. 如何在SpringDoc OpenAPI3中的折射文件？
2. https://github.com/springdoc/springdoc-openapi/issues/1432
3. https://github.com/springdoc/springdoc-openapi/issues/17

Answer 1

据我所知，ref值似乎期望一个可以找到模式的url？我看到有人建议创建一个endpoint来返回示例？这对我来说似乎有点过分。。。

我决定最简单的事情就是添加一些东西来从文件中提取示例并将它们插入OpenApi对象。

我在Spring配置中实现了OpenApiCustomiser，这允许我指向应用程序资源文件夹中的文件以获取响应示例。

我这样注释Controller方法：

@ApiResponses(value = {
    @ApiResponse(responseCode = "200",
        content = { @Content(mediaType = "application/json", 
        schema = @Schema(implementation = SomeResponse.class, 
                  name = "YourResponse"),  
                  examples = {@ExampleObject(value = "@your_data_200_response.json")}) }) 
    })

要使上述内容正常工作，请添加以下 OpenApiCustomiser 配置 bean：

@Bean
public OpenApiCustomiser applyStandardOpenAPIModifications() {
    return openApi -> {
        Paths paths = new Paths();
        openApi.getPaths().entrySet().stream()
                .sorted(Map.Entry.comparingByKey())
                .forEach(stringPathItemEntry -> {
                    paths.addPathItem(stringPathItemEntry.getKey(), addExamples(stringPathItemEntry.getValue()));
                });
        openApi.setPaths(paths);
    };
}

private PathItem addExamples(PathItem pathItem) {
    if(pathItem.getPost() !=null)  {
        //Note you can also Do this to APIResponses to insert info from a file into examples in say, a 200 response.
            pathItem.getPost().getRequestBody().getContent().values().stream()
                    .forEach(c ->{
                        String fileName = c.getExample().toString().replaceFirst("@","");
                        ObjectNode node = null;
                        try {
                            //load file from where you want. also don't insert is as a string, it wont format properly
                            node = (ObjectNode) new ObjectMapper().readTree(methodToReadInFileToString(fileName)); 
                        } catch (JsonProcessingException e) {
                            throw new RuntimeException(e);
                        }
                        c.setExample(node);
                    }
            );
    }
    return pathItem;
}

我只是从包含. json文件的 /resources文件夹中加载文件。