OpenAPI 规范在早期版本（openapi-generator 3.x）中有效，但在较新版本中验证失败

Question

我正在尝试为其 API 描述为 OpenAPI 文件 (https://developer.loadsmart.com/api/openapi.yaml) 的服务生成服务器存根，我正在尝试使用 openapi-generator (https://github.com/OpenAPITools/openapi-generator) 来完成此操作。

在检查存储库的先前版本 (3.3.4) 时，我可以这样验证 api 文件：

$ java -jar openapi-generator-cli-3_3_4.jar validate -i api.yaml
Validating spec (api.yaml)
No validation issues detected.

当使用 4.3.1 版本的存储库（我相信是最新的 4.x 分支版本）时，API 文件不再验证：

$ java -jar openapi-generator-cli-4_3_1.jar validate -i api.yaml
Validating spec (api.yaml)
[main] ERROR i.s.parser.SwaggerCompatConverter - failed to read resource listing
com.fasterxml.jackson.core.JsonParseException: Unrecognized token 'openapi': was expecting (JSON String, Number, Array, Object or token 'null', 'true' or 'false')
 at [Source: (StringReader); line: 1, column: 8]
    at com.fasterxml.jackson.core.JsonParser._constructError(JsonParser.java:1840)
    at com.fasterxml.jackson.core.base.ParserMinimalBase._reportError(ParserMinimalBase.java:722)
    at com.fasterxml.jackson.core.json.ReaderBasedJsonParser._reportInvalidToken(ReaderBasedJsonParser.java:2868)
    at com.fasterxml.jackson.core.json.ReaderBasedJsonParser._handleOddValue(ReaderBasedJsonParser.java:1914)
    at com.fasterxml.jackson.core.json.ReaderBasedJsonParser.nextToken(ReaderBasedJsonParser.java:773)
    at com.fasterxml.jackson.databind.ObjectMapper._readTreeAndClose(ObjectMapper.java:4231)
    at com.fasterxml.jackson.databind.ObjectMapper.readTree(ObjectMapper.java:2711)
    at io.swagger.parser.SwaggerCompatConverter.readResourceListing(SwaggerCompatConverter.java:210)
    at io.swagger.parser.SwaggerCompatConverter.read(SwaggerCompatConverter.java:123)
    at io.swagger.parser.SwaggerCompatConverter.readWithInfo(SwaggerCompatConverter.java:94)
    at io.swagger.parser.SwaggerParser.readWithInfo(SwaggerParser.java:42)
    at io.swagger.v3.parser.converter.SwaggerConverter.readLocation(SwaggerConverter.java:89)
    at io.swagger.parser.OpenAPIParser.readLocation(OpenAPIParser.java:16)
    at org.openapitools.codegen.cmd.Validate.execute(Validate.java:52)
    at org.openapitools.codegen.cmd.OpenApiGeneratorCommand.run(OpenApiGeneratorCommand.java:32)
    at org.openapitools.codegen.OpenAPIGenerator.main(OpenAPIGenerator.java:61)
[main] ERROR i.s.parser.SwaggerCompatConverter - failed to read resource listing
com.fasterxml.jackson.core.JsonParseException: Unrecognized token 'openapi': was expecting (JSON String, Number, Array, Object or token 'null', 'true' or 'false')
 at [Source: (StringReader); line: 1, column: 8]
    at com.fasterxml.jackson.core.JsonParser._constructError(JsonParser.java:1840)
    at com.fasterxml.jackson.core.base.ParserMinimalBase._reportError(ParserMinimalBase.java:722)
    at com.fasterxml.jackson.core.json.ReaderBasedJsonParser._reportInvalidToken(ReaderBasedJsonParser.java:2868)
    at com.fasterxml.jackson.core.json.ReaderBasedJsonParser._handleOddValue(ReaderBasedJsonParser.java:1914)
    at com.fasterxml.jackson.core.json.ReaderBasedJsonParser.nextToken(ReaderBasedJsonParser.java:773)
    at com.fasterxml.jackson.databind.ObjectMapper._readTreeAndClose(ObjectMapper.java:4231)
    at com.fasterxml.jackson.databind.ObjectMapper.readTree(ObjectMapper.java:2711)
    at io.swagger.parser.SwaggerCompatConverter.readResourceListing(SwaggerCompatConverter.java:210)
    at io.swagger.parser.SwaggerCompatConverter.read(SwaggerCompatConverter.java:123)
    at io.swagger.parser.SwaggerCompatConverter.readWithInfo(SwaggerCompatConverter.java:94)
    at io.swagger.parser.SwaggerParser.readWithInfo(SwaggerParser.java:42)
    at io.swagger.v3.parser.converter.SwaggerConverter.readLocation(SwaggerConverter.java:89)
    at io.swagger.parser.OpenAPIParser.readLocation(OpenAPIParser.java:16)
    at org.openapitools.codegen.cmd.Validate.execute(Validate.java:52)
    at org.openapitools.codegen.cmd.OpenApiGeneratorCommand.run(OpenApiGeneratorCommand.java:32)
    at org.openapitools.codegen.OpenAPIGenerator.main(OpenAPIGenerator.java:61)
Exception in thread "main" java.lang.NullPointerException
    at java.util.HashSet.<init>(HashSet.java:119)
    at org.openapitools.codegen.cmd.Validate.execute(Validate.java:54)
    at org.openapitools.codegen.cmd.OpenApiGeneratorCommand.run(OpenApiGeneratorCommand.java:32)
    at org.openapitools.codegen.OpenAPIGenerator.main(OpenAPIGenerator.java:61)

最后，当使用 5.0 版本（5.0.0 或 5.0.1）时，API 文件似乎有额外的验证问题：

java -jar openapi-generator-cli-5_0_0.jar validate -i api.yaml
Validating spec (api.yaml)
Errors:
    - attribute
      paths.'/api/v2/load-offers/offers/{offer_id}/related'(get).responses.200.content.'application/json'.schema.items
      is missing
    - attribute
      paths.'/api/v2/matches/{match_id}/reject'(post).responses.200.content.'application/json'.schema.items
      is missing
    - attribute
      paths.'/api/v2/matches/{match_id}/accept'(post).responses.200.content.'application/json'.schema.items
      is missing
    - attribute
      paths.'/api/v2/load-offers/loads/'(get).responses.200.content.'application/json'.schema.items
      is missing
    - attribute
      paths.'/api/v2/matches/'(get).responses.200.content.'application/json'.schema.items is
      missing
    - attribute
      paths.'/api/v2/load-offers/loads/{load_id}'(get).responses.200.content.'application/json'.schema.items
      is missing
    - attribute
      paths.'/api/v2/load-offers/loads/{load_id}/related-offers'(get).responses.200.content.'application/json'.schema.items
      is missing
    - attribute paths.'/api/v2/carrier/{driver_id}'. Declared path parameter driver_id needs to
      be defined as a path parameter in path or operation level
    - attribute paths.'/api/v2/shippers/accounts/{account_id}'. Declared path parameter
      account_id needs to be defined as a path parameter in path or operation level
    - attribute
      paths.'/api/v2/shipments/{shipment_id}/appointment_suggestions?start_date={start_date}'.
      Declared path parameter shipment_id needs to be defined as a path parameter in path or
      operation level
    - attribute paths.'/api/v2/load-offers/offers/{offer_id}'. Declared path parameter offer_id
      needs to be defined as a path parameter in path or operation level
    - attribute paths.'/api/v2/intermodal/quotes/{batch_id}'. Declared path parameter batch_id
      needs to be defined as a path parameter in path or operation level
    - attribute
      paths.'/api/v2/load-offers/offers/{offer_id}'(get).responses.200.content.'application/json'.schema.items
      is missing
    - attribute paths.'/api/v2/capacity/{capacity_ref_number}'. Declared path parameter
      capacity_ref_number needs to be defined as a path parameter in path or operation level
    - attribute
      paths.'/api/v2/load-offers/offers'(get).responses.200.content.'application/json'.schema.items
      is missing
    - attribute paths.'/api/v2/shipments/{shipment_id}'. Declared path parameter shipment_id
      needs to be defined as a path parameter in path or operation level
Warnings:
    - Unused model: PhoneNumber
    - Unused model: EquipmentType
    - Unused model: TotalWidth
    - Unused model: TotalLength
    - Unused model: TotalHeight
    - Unused model: Requirements
    - Unused model: ShipmentMode

[error] Spec has 16 errors.

我试图理解为什么在新版本的 openapi-generator 中似乎引入了更严格的验证，而没有任何明显的选项来更新旧文件。我正在使用的 api.yaml 文件的 OpenAPI 规范版本是 3.0.1。我曾尝试在 OpenAPI 和 Swagger 网站上寻找任何线索，以获取在不同版本的 openapi-generator 之间进行更改的线索，但我没有提出任何非常有用的建议。

Answer 1

我能够复制它。

This commit 是引入更改的那个，它链接到this issue：

问题在于 validate 的行为方式与 generate 的行为方式不同，因此他们引入了相同类型的验证。

有关更多详细信息，validate 命令现在进行以下调用

SwaggerParseResult result = new OpenAPIParser().readLocation(spec, null, options);