Swagger 响应关联对象

Question

我使用带有 OpenAPI 3 的 SwaggerHub 来定义 API。一条路线 GET /foo/{id] 应该 return 给定 id 的 foo 对象及其关联的 bar 对象。 API 将 return 类似于：{id: 4, name: 'test', bars: [{id: 53, name: 'barName1'}, {id: 87, name: 'barName2'}]}。 IE。 foo 和 bar.

之间存在多对多关系

如何在 OpenAPI 3 语法中描述它？我试过使用 anyOf 属性。到目前为止我有：

paths:
  /foo/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items: 
                  $ref: '#/components/schemas/Foo'
                anyOf:
                  - $ref: '#/components/schemas/Bar'

但这似乎没有在 UI 中显示正确的架构（在 UI 中没有提到 Bar）。

Answer 1

您不需要 anyOf。 anyOf 表示替代方案 ("either Foo or Bar")，而您有一个通常的嵌套结构 - 对象 Foo 和属性 bars 是 [= 的数组15=]秒。这可以描述为：

      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Foo'

components:
  schemas:
    Foo:
      type: object
      properties:
        bars:
          type: array
          items:
            $ref: '#/components/schemas/Bar'
      required:
        - bars
    Bar:
      ...

Swagger 响应关联对象

Swagger respond with associated objects

api-design

swagger

swagger-ui

openapi