对swagger 2.0上的模型的属性引用(嵌套)

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到对象模式,因为该类型不是从其他关键字推断出来的.

Answer 2

这是另一个有效的技巧。此解决方案适用于 OpenAPI 3 \xe2\x80\x93 最新版本的 OpenAPI 规范作为回答此问题的要点。

\n\n

就是这样：

\n\n

假设我有一个User带有枚举的模型State。我State在不同的模式中定义了枚举，然后在User模式中引用它。

\n\n

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

\n\n

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

\n\n

就这样。

\n\n

我希望这有帮助

\n