使用 Enunciate 记录返回二进制文件的端点 (image/png)

Question

我正在使用 Enunciate 来记录用 spring-webmvc 编写的 REST 服务。一些端点 return 图片。（请忽略这样一个事实，即这些图像可以由 nginx 或 apache 网络服务器等其他进程提供更好的服务。）

我正在尝试配置 Enunciate 以记录以下功能，但我不知道如何：

注释此方法以记录它 return 是一个二进制文件（通常是 png，但将来请求者可以请求 jpg 或 png）
提供一个显示“/hcm?empl_id=12345”的例子。方法上的 @DocumentationExample 和 emplId 上的 @DocumentationExample 都被忽略。

是否可以使用 Enunciate 对此进行记录？我需要打开什么东西吗？我开始认为 Enunciate 不会完成我的任务。

/**
 * Returns the HCM photo (image/png) for the staff member with the specified empl_id. If no such
 * image exists, return a 404.
 *
 * @pathExample /hcm?id=12345
 * 
 * @param idType currently only supports "hcm".
 *
 * @param emplId is the HCM EMPLID or the Active Directory EmployeeNumber for a given staff
 *        member
 *
 * @throws IOException when there is a problem accessing the image.
 */

@Override
@GetMapping(value = "/hcm", produces = {MediaType.IMAGE_PNG_VALUE})
@DocumentationExample(value = "/hcm?empl_id=12345")
public void getHcmPhoto(
        @RequestParam(value = "id_type", required = false, defaultValue = "hcm") String idType,
        @DocumentationExample(value = "12345")
        @RequestParam("empl_id") String emplId,
        HttpServletResponse response) throws IOException {
    logger.trace("/hcm call made for emplHcmId: {} {}", idType, emplId);
    final String emplHcmId = getHcmId(idType, emplId);

    if (emplHcmId == null) {
        response.setStatus(HttpStatus.NOT_FOUND.value());
        return;
    }

    File fileToSent = new File(pathToImages, emplHcmId + ".png");
    if (!fileToSend.exists()) {
        logger.debug("Photo {} does not exist", fileToSend.getAbsolutePath());
        response.setStatus(HttpStatus.NOT_FOUND.value());
        return;
    }

    try (InputStream in = new FileInputStream(fileToSend)) {
        logger.trace("Photo {} found", fileToSend.getAbsolutePath());
        response.setContentType(MediaType.IMAGE_PNG_VALUE);
        IOUtils.copy(in, response.getOutputStream());
    }
    catch (IOException ioe) {
        logger.error("Could not send {}: {}", fileToSend.getName(), ioe.getMessage(), ioe);
        throw ioe;
    }
}

我正在使用 Maven 进行构建。我正在构建源 jar 并在 .war 文件中引用它们

<plugin>
    <groupId>com.webcohesion.enunciate</groupId>
    <artifactId>enunciate-maven-plugin</artifactId>
    <version>${enunciate.version}</version>
    <executions>
        <execution>
            <id>assemble</id>
            <goals>
                <goal>assemble</goal>
            </goals>
            <configuration>
                <sourcepath-includes>
                    <include pattern="com.foo.**">
                        <!-- configure Enunciate to look for the source jars for all dependencies 
                            in the "com.foo.domain" groupId. -->
                        <groupId>com.foo.staff</groupId>
                        <artifactId>com.foo.staff.photo.controller</artifactId>
                    </include>
                </sourcepath-includes>
                <!-- but exclude com.foo.domain:domain-utils <sourcepath-excludes> <exclude>
                        <groupId>com.foo.domain</groupId> <artifactId>domain-utils</artifactId>
                    </exclude> </sourcepath-excludes> -->
                <docsDir>${project.build.directory}/docs</docsDir>
            </configuration>
        </execution>
    </executions>
</plugin>

我的enunciate.xml包含

<?xml version="1.0" encoding="UTF-8"?>
<enunciate xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://enunciate.webcohesion.com/schemas/enunciate-1.27.xsd">

<!-- 
    <facets>
        <exclude name="internal_api" />
    </facets>
 -->

    <api-classes>
        <include pattern="com.foo.**" />
        <exclude pattern="org.springframework.**" />
    </api-classes>


    <modules>
        <docs docsDir="target/docs" title="Staff Photo REST API"/>
        <spring-web />
    </modules>

</enunciate>

Answer 1

我通过返回 ResponseEntity 而不是返回 void 和操作 HttpServletResponse 来解决这个问题。即

@Override
@GetMapping(value = "/hcm", produces = {MediaType.IMAGE_PNG_VALUE})
public ResponseEntity<Resource> getHcmPhoto(
        @RequestParam(value = "id_type", required = false, defaultValue = "hcm") String idType,
        @RequestParam("empl_id") String emplId) throws IOException {
    logger.trace("/hcm call made for emplHcmId: {} {}", idType, emplId);
    final String emplHcmId = getHcmId(idType, emplId);

    HttpHeaders headers = new HttpHeaders();

    if (emplHcmId == null) {
        return new ResponseEntity<>(null, headers, HttpStatus.NOT_FOUND);
    }

    File hcmPhoto = getHcmPhotoFile(emplHcmId);
    if (hcmPhoto == null) {
        return new ResponseEntity<>(null, headers, HttpStatus.NOT_FOUND);
    }

    return new ResponseEntity<>(new org.springframework.core.io.FileUrlResource(hcmPhoto.toURI().toURL()),
            headers, HttpStatus.OK);
}

总的来说，无论是在 Enunciate 记录它的方式还是代码的阅读方式方面，这似乎都更好。双赢！

使用 Enunciate 记录返回二进制文件的端点 (image/png)

Use Enunciate to document an endpoint returning a binary file (image/png)

spring-mvc

enunciate