OpenAPI无法解析参考外部文件。组件名称包含无效字符

Question

我正在尝试将一个大的YML分成一堆较小的YML文档。我遵循了大卫·加西亚（David Garcia）提供的示例在这里< /a>，然后使用OpenAPI CodeGenerator生成我的模型。 OpenAPI Generator抱怨 [BUG]属性组件.schemas.schema名称不遵守正则表达式 ^[A-ZA-Z0-9 .-_]+$ 。因此，我试图通过克隆他的回购并在当地部署他的榜样与David Garcia的榜样一起玩，但我遇到了同样的错误。 https://editor.swagger.io/”中检查它。

Semantic error at components.schemas.$ref
Component names can only contain the characters A-Z a-z 0-9 - . _
Jump to line 25

我决定在

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Swagger Petstore
  description: Multi-file boilerplate for OpenAPI Specification.
  license:
    name: MIT
  contact:
    name: API Support
    url: http://www.example.com/support
    email: [email protected]
servers:
  - url: http://petstore.swagger.io/v1
tags:
  - name: pets
paths:
  /pets:
    $ref: "./resources/pets.yaml"
  /pets/{petId}:
    $ref: "./resources/pet.yaml"
components:
  parameters:
    $ref: "./parameters/_index.yaml"
  schemas:
    $ref: "./schemas/_index.yaml"
  responses:
    $ref: "./_index.yaml"

您可以轻松地将其粘贴到编辑器并亲自查看错误。 OpenAPI规范说 components既可以是对象对象或参考，IE 映射[字符串，架构对象|参考对象] ，和：“或者，每当可以使用架构对象时，可以在其位置使用参考

对象

components:
  parameters:
    petId:
      $ref: "./parameters/path/petId.yaml"
  schemas:
    pets:
      $ref: "./schemas/Pets.yaml"
  responses:
    responseSchema:
      $ref: "./response/pets200.yaml"

。为什么我不能引用外部索引？ 在线示例

Answer 1

这是一个普遍的误解，即OpenAPI规范允许 $ ref whery 。实际上， $ ref 仅在OpenAPI规范说字段的值可以是“参考对象”或“架构对象”的地方允许。

具体来说，此片段不是有效的OpenAPI语法：

components:
  parameters:
    $ref: "./parameters/_index.yaml"
  schemas:
    $ref: "./schemas/_index.yaml"
  responses:
    $ref: "./_index.yaml"

MAP [String，架构对象|参考对象] 表示 components.schemas 节点必须是一个映射，其中键是架构名称，并且值是内联架构或架构引用。如您的第二个示例（有效的OpenAPI语法）：

components:
  parameters:                              # Map
    petId:                                 #  <string, 
      $ref: "./parameters/path/petId.yaml" #           Reference Object>
  schemas:
    pets:
      $ref: "./schemas/Pets.yaml"
  responses:
    responseSchema:
      $ref: "./response/pets200.yaml"

某些实现用于处理$ refs的解决方案的方法是使用通用JSON $ REF RESOLVER预先处理规格（例如 json-refs ）来解决这些非标准$ refs。例如，博客文章您从使用 Swagger-Cli 中获取了此示例来解决非标准$ refs并创建一个合并的文件。