用于 Java 生成不一致类的 OpenAPI Maven 插件

如何解决用于 Java 生成不一致类的 OpenAPI Maven 插件

我们使用 openapi-generator-maven-plugin 版本 5.0.1 来生成我们的 API。我正在尝试指定一个包含 DTO 和文件的请求。

第一个奇怪的是，生成的代码没有使用 DTO，它基本上将字段扁平化，因此 API 期望指定每个字段。然而，我们并不太关心这个问题，因为我们可以只指定每个字段（尽管如果它按预期工作会很好）。

正在扼杀我们的问题是为 API 和 API Delegate 生成的类彼此不一致。生成的 API 将每个字段视为 String。但是，API 委托将它们视为 Optional<String>。因此，当我们尝试编译代码时，API 会收到编译错误，因为它正在将 String 传递给 Delegate，而 Delegate 需要 Optional<String>。

这是我们的 POM，以及相关的依赖项和插件配置：

        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.6.2</version>
        </dependency>
        <dependency>
            <groupId>org.openapitools</groupId>
            <artifactId>jackson-databind-nullable</artifactId>
            <version>0.2.1</version>
        </dependency>
        <dependency>
            <groupId>javax.validation</groupId>
            <artifactId>validation-api</artifactId>
            <version>2.0.1.Final</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
...
<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>5.0.1</version>
    <executions>
        <execution>
            <id>processor-Generate</id>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>
                    ${project.basedir}/apis/innovation-ivp-inventory-accuracy-acl-api.yml
                </inputSpec>
                <generatorName>spring</generatorName>
                <apiPackage>${project.groupId}.inventory.accuracy.acl.api</apiPackage>
                <modelPackage>${project.groupId}.inventory.accuracy.acl.dto</modelPackage>
                <invokerPackage>${project.groupId}.inventory.accuracy.acl.api.handler</invokerPackage>
                <supportingFilesToGenerate>ApiUtil.java,OpenAPIDocumentationConfig.java
                </supportingFilesToGenerate>
                <configOptions>
                    <useTags>true</useTags>
                    <dateLibrary>java8-localdatetime</dateLibrary>
                    <java8>true</java8>
                    <delegatePattern>true</delegatePattern>
                    <useBeanValidation>true</useBeanValidation>
                    <uSEOptional>true</uSEOptional>
                    <configPackage>${project.groupId}.inventory.accuracy.acl.api</configPackage>
                </configOptions>
                <output>${project.build.directory}/generated-sources</output>
            </configuration>
        </execution>
    </executions>
</plugin>

这是我们的 OpenAPI 规范：

'/email':
  post:
    tags:
      - email-service
    summary: Email Service
    operationId: sendEmail
    requestBody:
      required: true
      content:
        multipart/mixed:
          schema:
            allOf:
              - $ref: '#/components/schemas/EmailRequestDTO'
              - type: object
                properties:
                  file:
                    type: string
                    format: binary
    responses:
      "200":
        description: OK
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailResponseDTO'
components:
  schemas:
    EmailRequestDTO:
      type: object
      properties:
        sendTo:
          type: string
        sentFrom:
          type: string
        subject:
          type: string
        content:
          type: string
    EmailResponseDTO:
      type: object
      properties:
        status:
          type: string
        errorMessage:
          type: string

这里是OpenAPI生成的API类（注意参数都是String）：

public interface EmailServiceApi {

    @ApiOperation(value = "Email Service",nickname = "sendEmail",notes = "",response = EmailResponseDTO.class,tags={ "email-service",})
    @ApiResponses(value = {
        @ApiResponse(code = 200,message = "OK",response = EmailResponseDTO.class) })
    @PostMapping(
        value = "/email",produces = { "application/json" },consumes = { "multipart/mixed" }
    )
    default ResponseEntity<EmailResponseDTO> sendEmail(@ApiParam(value = "") @Valid @RequestPart(value = "sendTo",required = false)  String sendTo,@ApiParam(value = "") @Valid @RequestPart(value = "sentFrom",required = false)  String sentFrom,@ApiParam(value = "") @Valid @RequestPart(value = "subject",required = false)  String subject,@ApiParam(value = "") @Valid @RequestPart(value = "content",required = false)  String content,@ApiParam(value = "") @Valid @RequestPart(value = "file",required = false) multipartfile file) {
        return getDelegate().sendEmail(sendTo,sentFrom,subject,content,file);
    }
}

这里是OpenAPI生成的API Delegate类（注意参数都是Optional）：

public interface EmailServiceApiDelegate {
    default ResponseEntity<EmailResponseDTO> sendEmail(Optional<String> sendTo,Optional<String> sentFrom,Optional<String> subject,Optional<String> content,multipartfile file) {
        getRequest().ifPresent(request -> {
            for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
                if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {
                    String exampleString = "{ \"errorMessage\" : \"errorMessage\",\"status\" : \"status\" }";
                    ApiUtil.setExampleResponse(request,"application/json",exampleString);
                    break;
                }
            }
        });
        return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
    }
}

解决方法

使用 allOf 将列出的所有架构合二为一。 EmailRequestDTO 的属性和内联定义的对象的属性作为参数而不是 DTO 生成。见https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/#allof

如果您不想在委托中生成可选字符串作为参数，请删除 useOptional 配置。见https://openapi-generator.tech/docs/generators/spring/