Spring REST Docs 中的文档图像响应

Question

我有一个生成随机图像的 REST 端点。我正在使用 Spring REST Docs，但响应在 http-response.adoc 文件中都是乱码。 Mock MVC 和 REST Docs 是否有一种简单的方法可以将文件存储在某处，以便我的 .adoc 文件可以引用它？

Answer 1

不是完美但可行的解决方案：

class ImageSnippet implements Snippet {

    private final String filePath;

    public ImageSnippet(String filePath) {
        this.filePath = filePath;
    }

    @Override
    public void document(Operation operation) throws IOException {
        byte[] picture = operation.getResponse().getContent();

        Path path = Paths.get(filePath);
        Files.deleteIfExists(path);
        Files.createDirectories(path.getParent());
        Files.createFile(path);

        try (FileOutputStream fos = new FileOutputStream(path.toFile())) {
            fos.write(picture);
        }
    }
}

以及在MockMvc测试中的使用（图片文件夹路径很重要）：

    mockMvc.perform(get("/my-profile/barcode")
                      .accept(MediaType.IMAGE_PNG))
            .andExpect(status().isOk())
            .andDo(document("my-profile/barcode",
                      new ImageSnippet("build/asciidoc/html5/images/barcode.png")));

在.adoc 模板中：

 image::barcode.png[]

这是我的build.gradle Asciidoctor 配置（imagesdir 很重要）：

asciidoctor {
    dependsOn test
    backends = ['html5']
    options doctype: 'book'

    attributes = [
            'source-highlighter': 'highlightjs',
            'imagesdir'         : './images',
            'toc'               : 'left',
            'toclevels'         : 3,
            'numbered'          : '',
            'icons'             : 'font',
            'setanchors'        : '',
            'idprefix'          : '',
            'idseparator'       : '-',
            'docinfo1'          : '',
            'safe-mode-unsafe'  : '',
            'allow-uri-read'    : '',
            'snippets'          : snippetsDir,
            linkattrs           : true,
            encoding            : 'utf-8'
    ]

    inputs.dir snippetsDir
    outputDir 'build/asciidoc'
    sourceDir 'src/docs/asciidoc'
    sources {
        include 'index.adoc'
    }
}

Answer 2

您可以做的是实现一个自定义代码段，以保存结果响应。可以使用接收到的操作的RestDocumentationContext属性来获取输出目录。

    mockMvc.perform(get("/example"))
            .andDo(document("some-example", operation -> {
                var context = (RestDocumentationContext) operation.getAttributes().get(RestDocumentationContext.class.getName());
                var path = Paths.get(context.getOutputDirectory().getAbsolutePath(), operation.getName(), "response-file.png");
                Files.createDirectories(path.getParent());
                Files.write(path, operation.getResponse().getContent());
            }));

但是，这将在您的输出目录中创建一个 .png 文件，如果您在需要嵌入它的源目录中有 Asciidoc，这通常不是很有用。因此，您可以改为创建一个 Asciidoc 文件，其中包含图像标签的自定义 HTML，其源是响应的 base64 表示。

    mockMvc.perform(get("/example"))
            .andDo(document("some-example", operation -> {
                var context = (RestDocumentationContext) operation.getAttributes().get(RestDocumentationContext.class.getName());
                var path = Paths.get(context.getOutputDirectory().getAbsolutePath(), operation.getName(), "response-file.adoc");
                var outputStream = new ByteArrayOutputStream();
                outputStream.write("++++\n".getBytes());
                outputStream.write("<img src=\"data:image/png;base64,".getBytes());
                outputStream.write(Base64.getEncoder().encode(operation.getResponse().getContent()));
                outputStream.write("\"/>\n".getBytes());
                outputStream.write("++++\n".getBytes());
                Files.createDirectories(path.getParent());
                Files.write(path, outputStream.toByteArray());
            }));

虽然在空间方面会增加一些开销，但如果您使用它，则无需从源代码中引用构建文件。

Answer 3

如果您不需要/不想在文档中显示图像，另一种方法是：使用 ContentModifyingOperationPreprocessor 将字节替换为一些字符串，让文档的读者清楚地知道会有一些图像响应中的字节数。

例如：

        mockMvc.perform(get("/api/users/{id}/avatar", user.getId().asString())
                                .with(createCustomerAuth()))
               .andExpect(status().isOk())
               .andDo(document("get-user-avatar-example",
                               null,
                               Preprocessors.preprocessResponse(new ContentModifyingOperationPreprocessor(new ContentModifier() {
                                   @Override
                                   public byte[] modifyContent(byte[] originalContent, MediaType contentType) {
                                       return "<< IMAGE BODY HERE >>".getBytes(StandardCharsets.UTF_8);
                                   }
                               }))));

这会生成一个像这样的adoc 文件：

[source,http,options="nowrap"]
----
HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 15
Cache-Control: max-age=3600

<< IMAGE BODY HERE >>
----