OpenApi 3 从外部文件导入模式

Question

我正在为 Web 服务定义通用模式，并且我想将它们导入到规范的组件/模式部分。我想创建一个跨多个服务通用的规范数据模型，以避免在每个服务定义中重新定义相似的对象。

有没有办法做到这一点？是否有与 XSD 对其导入标签所做的类似的机制？

Answer 1

您可以$ref使用绝对或相对 URL 直接外部 OpenAPI 架构对象：

responses:
  '200':
    description: OK
    schema:
      $ref: './common/Pet.yaml'
      # or
      # $ref: 'https://api.example.com/schemas/Pet.yaml'

其中 Pet.yaml 包含，例如：

type: object
properties:
  id:
    type: integer
    readOnly: true
  petType:
    type: string
  name:
    type: string
required:
  - id
  - petType
  - name

有关更多信息，请参阅使用 $ref。

Answer 2

如果 Pet.yaml 不是一个普通对象而是有几个像这样的对象，那么扩展 Helen 对那些从 Google 登陆这里的人的回答：

components:
  schemas:
    pet:
      type: object
      properties:
        (...)

你可以这样引用它：

$ref: './common/Pet.yaml#/components/schemas/pet'