在 swagger OpenApi 3.0 yaml 文件中的路径中包含架构组件答案

【问题标题】：Include schema components inside paths in swagger OpenApi 3.0 yaml file在 swagger OpenApi 3.0 yaml 文件中的路径中包含架构组件
【发布时间】：2019-12-04 11:42:38
【问题描述】：

我正在为 drupal 开发 API，并且我创建了一些可重用的组件，当我尝试在其中一个未显示的路径中“包含”组件时

这是我的文件：

标题组件

  #HEADER (JSONAPI)
    header:
      required:
        - jsonapi
        - data
        - links
      properties:
        jsonapi:
          required:
            - version
            - meta
          properties: 
            version:
              type: "string"
              example: "1.0"
            meta:
              required:
                - links
              properties:
                self:
                  required:
                    - href
                  properties:
                    href:
                      type: "string"
                      example: "http://jsonapi.org/format/1.0/"
                  type: object
              type: object
          type: object
      type: object
  #END OF HEADER

链接组件

#Links
    links:
      required:
        - self
      properties:
        self: 
          required:
            - href
          properties:
            href:
              type: "string"
              example: "http://localhost/jsonapi/link/be336992-26b9-448e-af00-2fb55642d933"
          type: object
      type: object

数据组件

#Data Link

    data:
      type: "array"
      items: 
        type: "object"
        properties: 
          type: 
            type: "string"
            example: "node--link"
          id: 
            type: "string"
            example: "12c800a8-ee1d-4fde-9bf6-9479a57f9588"
          attributes: 
            required: 
              - "drupal_internal__nid"
              - "drupal_internal__vid"
              - "status"
              - "title"
              - "created"
              - "path"
              - "body"
              - "url"
            properties: 
              drupal_internal__nid: 
                type: "number"
                example: 8
              drupal_internal__vid: 
                type: "number"
                example: 8
              status: 
                type: "boolean"
                example: true
              title: 
                type: "string"
                example: "Test Link"
              created: 
                type: "string"
                example: "2019-12-04T10:11:58+00:00"
              path: 
                required: 
                  - "alias"
                  - "pid"
                  - "langcode"
                properties: 
                  alias: 
                    type: "string"
                    example: "/link/test-link"
                  pid: 
                    type: "number"
                    example: 8
                  langcode: 
                    type: "string"
                    example: "en"
                type: "object"
              body: 
                required: 
                  - "value"
                  - "format"
                  - "processed"
                  - "summary"
                properties: 
                  value: 
                    type: "string"
                    example: "<p>This is a test link</p>\r\n"
                  format: 
                    type: "string"
                    example: "basic_html"
                  processed: 
                    type: "string"
                    example: "<p>This is a test link</p>"
                  summary: 
                    type: "string"
                    example: ""
                type: "object"
              url: 
                type: "string"
                example: "http://www.example.com"
            type: "object"
          relationships: 
            required: 
              - "node_type"
              - "uid"
              - "link"
            properties: 
              node_type: 
                required: 
                  - "data"
                  - "links"
                properties: 
                  data: 
                    required: 
                      - "type"
                      - "id"
                    properties: 
                      type: 
                        type: "string"
                        example: "node_type"
                      id: 
                        type: "string"
                        example: "a95e770e-9035-4b8c-8c80-679ad9703174"
                    type: "object"
                  links: 
                    required: 
                      - "self"
                      - "related"
                    properties: 
                      self: 
                        required: 
                          - "href"
                        properties: 
                          href: 
                            type: "string"
                            example: "http://localhost/jsonapi/link/12c800a8-ee1d-4fde-9bf6-9479a57f9588/relationships/node_type?resourceVersion=id%3A8"
                        type: "object"
                      related: 
                        required: 
                          - "href"
                        properties: 
                          href: 
                            type: "string"
                            example: "http://localhost/jsonapi/link/12c800a8-ee1d-4fde-9bf6-9479a57f9588/node_type?resourceVersion=id%3A8"
                        type: "object"
                    type: "object"
                type: "object"
              uid: 
                required: 
                  - "data"
                  - "links"
                properties: 
                  links: 
                    required: 
                      - "self"
                    properties: 
                      self: 
                        required: 
                          - "href"
                        properties: 
                          href: 
                            type: "string"
                            example: "http://localhost/jsonapi/link/12c800a8-ee1d-4fde-9bf6-9479a57f9588/relationships/uid?resourceVersion=id%3A8"
                        type: "object"
                    type: "object"
                type: "object"
              link: 
                required: 
                  - "data"
                  - "links"
                properties: 
                  links: 
                    required: 
                      - "self"
                    properties: 
                      self: 
                        required: 
                          - "href"
                        properties: 
                          href: 
                            type: "string"
                            example: "http://localhost/jsonapi/link/12c800a8-ee1d-4fde-9bf6-9479a57f9588/relationships/link?resourceVersion=id%3A8"
                        type: "object"
                    type: "object"
                type: "object"
            type: "object"


  #end of data for link

这是我的路径：

paths:
  /link:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/header'
                  - $ref: '#/components/schemas/data'
                  - $ref: '#/components/schemas/links'

在 swagger 应用程序中仅显示标题和链接，缺少数据组件抱歉发了这么长的文件

【问题讨论】：

标签： drupal yaml swagger

【解决方案1】：

问题是allOf 中的子模式类型不兼容：header 和 links 模式是对象，但 data 是一个数组。这部分：

allOf:
  - $ref: '#/components/schemas/header'
  - $ref: '#/components/schemas/data'
  - $ref: '#/components/schemas/links'

相当于：

allOf:
  - # header
    type: object
    properties:
      jsonapi: ...

  - # data
    type: array   # <-----
    items: ...

  - # links
    type: object
    properties:
      self: ...

这是一个不可能的模式，因为一个实例不能同时是一个对象和一个数组。

假设数据数组应该被包装到data 属性中，您需要更改data 架构，如下所示：

components:
  schemas:
    data:
      type: object
      properties:
        data:
          type: array
          items:
            ...

【讨论】：