Question

我使用Enunciate来记录使用spring-webmvc编写的REST服务。一些端点返回图像。（请忽略这样的事实，即像nginx或apache webserver这样的其他进程可以更好地服务这些图像。）

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

注释此方法以记录它返回二进制文件（通常是png，但将来请求者将能够请求jpg或png）
提供一个显示＆＃34; / hcm？empl_id = 12345＆＃34;的示例。方法上的@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）

1 个答案: