swagger - 在 swagger 中，是否可以在一个文件中导入多个 yaml 文件？

Question

对于客户端，这是在 client.yaml 中

/clients:
    get:
      tags:
      - "Clients"
      description: "List Clients The list capability"
      produces:
      - "application/json"
      parameters:
      - name: "tenantIdentifier"
        in: "query"
        required: true
        type: "array"
        items:
          type: "string"
          enum:
          - "default"
      responses:
        200:
          description: "successful operation"
        400:
          description: "Invalid status value"
      security:
      - basicAuth: []
    post:
      tags:
      - "Clients"
      summary: "Create client if address is enabled"
      description: ""
      operationId: "addClient"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "tenantIdentifier"
        in: "query"
        description: ""
        required: true
        type: "array"
        items:
          type: "string"
          enum:
          - "default"
      - in: "body"
        name: "body"
        description: "Add what do you wnat to add "
        required: true
        schema:
          allOf:
            - $ref: '#/definitions/ClientStructure1'
            - $ref: '#/definitions/ClientStructure2'
            - $ref: '#/definitions/ClientStructure3'
      responses:
        405:
          description: "Invalid input"
      security:
      - basicAuth: []

对于 USER，这是在 user.yaml 中

  /users:
    get:
      tags:
      - "Users"
      summary: "Retrieve list of users"
      produces:
      - "application/json"
      parameters:
      - name: "tenantIdentifier"
        in: "query"
        required: true
        type: "array"
        items:
          type: "string"
          enum:
          - "default"
      responses:
        200:
          description: "successful operation"
        400:
          description: "Invalid status value"
      security:
      - basicAuth: []
    post:
      tags:
      - "Users"
      summary: "Adds new application user."
      description: "Note: Password information is not required (or processed). Password details at present are auto-generated and then sent to the email account given (which is why it can take a few seconds to complete)."
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "tenantIdentifier"
        in: "query"
        description: ""
        required: true
        type: "array"
        items:
          type: "string"
          enum:
          - "default"
      - in: "body"
        name: "body"
        description: "Mandatory Fields: username, firstname, lastname, email, officeId, roles, sendPasswordToEmail"
        required: true
        schema:
           $ref: "#/definitions/StructureForCreateUSer"          
      responses:
        400:
          description: ""
        404:
          description: ""
      security:
      - basicAuth: []

Answer 1

你不能$ref整个路径，但您可以 $ref各个路径的内容。在您的示例中，您可以使用:

paths:
  /clients:
    $ref: clients.yaml#/~1clients
  /users:
    $ref: users.yaml#/~1users

clients.yaml#/~1clients意味着我们采用 clients.yaml文件，然后读取 /clients 的内容该文件中的节点并替换 $ref有了那个内容。 ~1clients是 /clients与 /转义为 ~1根据 JSON 指针规则。

为了简化引用，您可以删除 /clients:和 /users:来自您的 clients.yaml 的节点和 users.yaml文件

# clients.yaml
get:
  description: "List Clients The list capability"
  ...
post:
  summary: "Create client if address is enabled"
  ...

然后使用

paths:
  /clients:
    $ref: clients.yaml
  /users:
    $ref: users.yaml