使用 jaxrs-spec 生成器从 OpenAPI 规范生成的接口返回 StreamingOutput

Question

在使用jaxrs-spec实现从 OpenAPI 规范生成的接口时，我想返回一个StreamingOutput 。 默认实现仅使用java.io.File作为返回值。

我们从数据库加载用户生成的数据，甚至 stream 从不同的服务加载它，并且希望避免为了符合接口而创建临时文件。

使用maven 插件的当前配置如下所示

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>6.2.0</version>
    <executions>
        <execution>
            <!-- <phase/> and <goals/> -->
            <configuration>
                <inputSpec>path/to/openapi/spec.yml</inputSpec>
                <generatorName>jaxrs-spec</generatorName>
                <configOptions>
                    <hideGenerationTimestamp>true</hideGenerationTimestamp>
                    <interfaceOnly>true</interfaceOnly>
                    <useSwaggerAnnotations>false</useSwaggerAnnotations>

                    <sourceFolder>src/main/java</sourceFolder>
                    <dateLibrary>java8</dateLibrary>

                    <title>${title}</title>
                    <apiPackage>com.example.api</apiPackage>
                    <modelPackage>com.example.model</modelPackage>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

通过此设置，我使用以下 OpenAPI 定义

/documents/{id}:
  get:
    summary: Get the given document as PDF
    operationId: getDocument
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    responses:
      200:
        description: Get the document
        content:
          application/pdf:
            schema:
              type: string
              format: binary
      302:
        description: Redirect to the location of the PDF document
        headers:
          Location:
            description: The URL from where to get the PDF document
            schema:
              type: string
      404:
        description: Document not found

这导致了这个方法

@GET
@Path("/{id}")
@Produces({ "application/pdf" })
File getDocument(@PathParam("id") String id)

如何使用 stream 将返回值更改为某个值，例如 StreamingOutput？ 或者，我也可以使用javax.ws.rs.core.Response 。

当我在生成器中设置returnResponse参数时，此方法将返回一个Response ，但是从此 OpenAPI 规范生成的所有其他方法也会返回一个，我需要调整所有实现和测试。

我已经按照这个答案中的建议研究了自定义模板，但是对于这么小的改变来说感觉太多了。

Answer 1

按照 Rob 的建议，通过 Maven 和openapi-generator-maven-plugin使用它时只需执行几个步骤

1. 创建一个新的 maven 模块。

2. 为扩展 JavaJAXRSSpecServerCodegen 的代码生成器创建一个class 。 这将添加"StreamingOutput"作为"file"和"binary"的类型映射（只有"file"足以满足我的规范）并且还添加了javax.ws.rs.core.StreamingOutput的导入

   public class JaxrsSpecStreamingOutputGenerator extends JavaJAXRSSpecServerCodegen { protected static final String GENERATOR_NAME = "jaxrs-spec-streamingoutput"; @Override public String getName() { return GENERATOR_NAME; } @Override public String getHelp() { return super.getHelp() + "\njava.io.File is replaced with " + StreamingOutput.class.getName(); } public JaxrsSpecStreamingOutputGenerator() { String shortName = "StreamingOutput"; importMapping.put(shortName, StreamingOutput.class.getName()); // use 'StreamingOutput' for 'binary' and 'file' typeMapping.put("binary", shortName); typeMapping.put("file", shortName); } }

   此代码生成器由jaxrs-spec-streamingoutput标识

3. 添加具有以下内容的META-INF/services/org.openapitools.codegen.CodegenConfig ：

    ${package}.JaxrsSpecStreamingOutputGenerator

   （将${package}替换为实际的 package 名称）

---

或者，maven 模块和使用 OpenAPI 生成器 CLI元命令生成的所有必要文件。

java -jar openapi-generator-cli-6.2.1.jar \
    meta \
    -o jaxrs-spec-streamingoutput \
    -n jaxrs-spec-streamingoutput \
    -p ${package}

（将${package}替换为实际的 package 名称）

从生成的模块中，只保留生成器 class 和META-INF/services中的CodegenConfig 。 按照上面第 2 步中的描述调整生成器 class。

---

然后可以安装 maven 模块 ( mvn install ) 并通过openapi-generator-maven-plugin 。 设置generatorName并包含 maven 模块作为插件依赖项：

<plugin>
   <groupId>org.openapitools</groupId>
   <artifactId>openapi-generator-maven-plugin</artifactId>
   <version>${plugin-version}</version>
   <executions>
      <execution>
         <phase>generate-resources</phase>
         <goals>...</goals>
         <configuration>
            <inputSpec>...</inputSpec>
            <!-- 1. set generator name -->
            <generatorName>jaxrs-spec-streamingoutput</generatorName>
            <configOptions>...</configOptions>
         </configuration>
      </execution>
   </executions>
   <dependencies>
      <dependency>
         <!-- 
            2. add this module to the dependencies
            e.g. '${project.groupId}:api-codegen:${version}'
         -->
      </dependency>
   </dependencies>
</plugin>

configOptions可以像在jaxrs-spec generator中一样使用。

Answer 2

您只需使用 TypeMapping+ImportMapping 就可以存档类似的结果

<plugin>
  <groupId>org.openapitools</groupId>
  <artifactId>openapi-generator-maven-plugin</artifactId>
  <version>6.2.1</version>
  <configuration>
    .. rest of configuration ..
    <typeMappings>
      <typeMapping>binary=OutputStream</typeMapping>
      <typeMapping>file=OutputStream</typeMapping>
    </typeMappings>
    <importMappings>
      <importMapping>OutputStream=my.custom.OutputStream</importMapping>
    </importMappings>
  </configuration>
  <executions>
    .. your executions ..       
  </executions>
</plugin>