为什么 openapi-generator 使用不存在的导入

Question

我正在使用openapi-codegen version 4.2.2并openapi specification 3.0.0从 yaml 文件生成一个 java 服务器 API，如下所示：

openapi-generator generate -i test.yaml -g spring -o /tmp/springTest

我遇到的问题是，生成的代码试图导入一个不存在的类。API 应该接受一个 pet 类型的对象并返回相同的 pet。宠物应该是猫、狗或蜥蜴。我使用了 openapi 规范中的继承示例，并从中构建了以下 yaml 文件：

openapi: 3.0.0
info:
  version: 1.0.0
  title: Three Pets
  termsOfService: http://swagger.io/terms
tags:
  - name: test
paths:
  /echoPet:
    post:
      tags:
        - test
      summary: Return input
      description: Send pet get pet
      operationId: echoPet
      parameters:
        - name: pet
          in: query
          schema:
            oneOf:
              - $ref: '#/components/schemas/Cat'
              - $ref: '#/components/schemas/Dog'
              - $ref: '#/components/schemas/Lizard'
      responses:
        "200":
          description: Pet sucesfully returned
          content:
            application/json:
                schema:
                  oneOf:
                    - $ref: '#/components/schemas/Pet'
servers:
  - url: https://localhost:8080/v2
  - url: http://localhost:8080/v2
components:
  schemas:
    Pet:
      type: object
      required:
      - pet_type
      properties:
        pet_type:
          type: string
      discriminator:
        propertyName: pet_type
        mapping:
          cachorro: Dog
    Cat:
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        # all other properties specific to a `Cat`
        properties:
          name:
            type: string
          huntingSkill:
            type: string
            description: The measured skill for hunting
            enum:
            - clueless
            - lazy
            - adventurous
            - aggressive
    Dog:
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        # all other properties specific to a `Dog`
        properties:
          bark:
            type: string
          packSize:
            type: integer
            format: int32
            description: the size of the pack the dog is from
            default: 0
            minimum: 0
    Lizard:
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        # all other properties specific to a `Lizard`
        properties:
          lovesRocks:
            type: boolean

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#discriminator-object

据我了解，它应该生成一个 API，该 API 接受以下类型 Cat、Dog、Lizard 之一。（如果我在这里使用 Pet，验证说，Pet 不是类型对象）生成的 EchoPetApi.java 使用导入：

import org.openapitools.model.OneOfCatDogLizard;
import org.openapitools.model.OneOfPet;

但是这些类并不存在，这会使代码无法编译。我在 org.openapitools.model 包中的所有内容是：

Cat.java
CatAllOf.java
Dog.java
DogAllOf.java
Lizard.java
LizardAllOf.java
Pet.java

这里的 Cat、Dog 和 Lizard.java 看起来和预期的一样并且都扩展了 Pet.java，但是 CatAllOf、DogAllOf 和 LizardAllOf 没有扩展任何东西，只有来自各自类的属性和稍微不同的 hashCode() 方法。

这是带有不存在的导入的 EchoPetApi.java（前两个，在包之后）：

/**
 * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech) (4.2.2).
 * https://openapi-generator.tech
 * Do not edit the class manually.
 */
package org.openapitools.api;

import org.openapitools.model.OneOfCatDogLizard;
import org.openapitools.model.OneOfPet;
import io.swagger.annotations.*;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RequestPart;
import org.springframework.web.context.request.NativeWebRequest;
import org.springframework.web.multipart.MultipartFile;

import javax.validation.Valid;
import javax.validation.constraints.*;
import java.util.List;
import java.util.Map;
import java.util.Optional;
@javax.annotation.Generated(value = "org.openapitools.codegen.languages.SpringCodegen", date = "2019-12-18T11:27:04.474+01:00[Europe/Berlin]")

@Validated
@Api(value = "echoPet", description = "the echoPet API")
public interface EchoPetApi {

    default Optional<NativeWebRequest> getRequest() {
        return Optional.empty();
    }

    @ApiOperation(value = "Return input", nickname = "echoPet", notes = "Send pet get pet", response = OneOfPet.class, tags={ "test", })
    @ApiResponses(value = { 
        @ApiResponse(code = 200, message = "Pet sucesfully returned", response = OneOfPet.class) })
    @RequestMapping(value = "/echoPet",
        produces = { "application/json" }, 
        method = RequestMethod.POST)
    default ResponseEntity<OneOfPet> echoPet(@ApiParam(value = "", defaultValue = "null") @Valid OneOfCatDogLizard pet) {
        return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);

    }

}

如果我使用 openapi-codegen 中的验证函数，它不会返回任何错误：

$ openapi-generator validate -i test.yaml
Validating spec (test.yaml)
No validation issues detected.

Answer 1

我对您的 openapi 规范做了一些更改，以使其在我这边工作

首先要更改的是 API 的参数/输入。将对象作为查询字符串发送很复杂

     parameters:
        - name: pet
          in: query
          schema:
            oneOf:
              - $ref: '#/components/schemas/Cat'
              - $ref: '#/components/schemas/Dog'
              - $ref: '#/components/schemas/Lizard'

所以更喜欢 requestBody 并像这样定义它：

    requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/Cat'
              - $ref: '#/components/schemas/Dog'
              - $ref: '#/components/schemas/Lizard'

然后，可以像这样管理响应（oneOf 指令对于您的情况不是强制性的）：

    responses:
        "200":
          description: Pet sucesfully returned
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/Pet'

Cat生成器现在将提供和使用Dog的接口Lizard

控制器将使用此接口，您将不再遇到编译/定义问题