Question

我很难弄清楚如何在swagger 2.0中嵌套模型。

目前我有：

SomeModel:
 properties:
   prop1:
     type: string
   prop2:
     type: integer
   prop3:
     type:
       $ref: OtherModel

OtherModel:
  properties:
    otherProp:
      type: string

我尝试了很多其他方法：

prop3:
  $ref: OtherModel
# or
prop3:
  schema:
    $ref: OtherModel
# or
prop3:
  type:
    schema:
      $ref: OtherModel

上述所有内容似乎都无效。

但是，对于数组工作正常：

prop3:
  type: array
  items:
    $ref: OtherModel

Answer 1

在OpenAPI 2.0中对其进行建模的正确方法是：

swagger: '2.0'
...

definitions:
  SomeModel:
    type: object
    properties:
      prop1:
        type: string
      prop2:
        type: integer
      prop3:
        $ref: '#/definitions/OtherModel'   # <-----

  OtherModel:
    type: object
    properties:
      otherProp:
        type: string

如果您使用的是OpenAPI 3.0，则模型会位于components/schemas而不是definitions：

openapi: 3.0.1
...

components:
  schemas:
    SomeModel:
      type: object
      properties:
        prop1:
          type: string
        prop2:
          type: integer
        prop3:
          $ref: '#/components/schemas/OtherModel'   # <-----

    OtherModel:
      type: object
      properties:
        otherProp:
          type: string

请记住将type: object添加到对象架构中，因为来自其他关键字的type is not inferred。

Answer 2

这是另一个可行的技巧。该解决方案适用于OpenAPI 3 – OpenAPI规范的最新版本，是回答此问题的要点。

方法是：

说，我有一个User枚举的State模型。我在另一个架构中定义了State枚举，然后在User架构中引用了它。

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        first_name:
          type: string
        last_name:
          type: string
        password:
          type: string
          format: password
        state:
          $ref: '#/components/schemas/State'
    State:
      type: string
      description: List of States
      enum:
        - State 1
        - State 2
        - State 3
        - State 4
        - State 5

请注意，此处的枚举表示为数组，如果您希望将其表示为哈希，请在Representing enum property in hash上查看此解决方案。

仅此而已。

我希望这会有所帮助

对swagger 2.0上的模型的属性引用（嵌套）

2 个答案: