GET

Question

我开始使用Swagger编辑器，我对可重用的定义有点困惑。作为一个例子，我有一个任务模型定义如下所示。

GET

GET调用将返回属于Task模型的所有元素。

POST

POST呼叫必须指定task_list_id，title和display_order。可能包含notes，due，assigned_id和parent_id。不应该从Task对象发送其他元素。

PATCH

PATCH调用不会在ident中发送，因为它将成为路径URL的一部分，但它会发送一个或多个其他元素。

如果指定了completed，那么也应该指定completor_id（我可以在PATCH方法的注释中指定这个...

definitions:
  Task:
    properties:
      ident:
        type: integer
        description: The SQL ident of the Task object
        readOnly: true
      task_list_id:
        type: integer
        description: The SQL ident of the Task List object this Task belongs to.
      assigned_id:
        type: integer
        description: The SQL ident of the Person who this task is assigned to.
      completor_id:
        type: integer
        description: The SQL ident of the Person who completed this task.
      created:
        type: integer
        description: The UTC epoch time this Task was created.
      completed:
        type: integer
        description: The UTC epoch time this Task was completed.
      due:
        type: integer
        description: The UTC epoch time this Task will be due.
      title:
        type: string
        description: The details of the Task
      notes:
        type: string
        description: Extra notes to clarify the Task requirements.
      display_order:
        type: integer
        description: The order that this task should be displayed in user visible lists.
      parent_id:
        type: integer
        description: The SQL ident of the Task that this is a sub-Task of.

Answer 1

在您的示例中，您需要为GET，PUT和PATCH定义单独的模型，并复制每个模型中的属性。

为什么：虽然Swagger在某种程度上支持model inheritance/composition，但您的模型不能相互继承，因为它们都具有不同的必需属性。不支持扩展基本模型，同时覆盖其所需的属性。

但是，如果您手动编写YAML（而不是从代码生成YAML），则可以通过使用YAML功能（例如anchors（&，*）来避免代码重复， merge keys（<<）。 这是否有效取决于您的工具是否支持这些YAML功能。^脚注 Swagger编辑器和Swagger UI支持它们，但我不了解其他工具。

以下是帮助您了解这个想法的示例：

BaseModel:
  properties: &base-model-properties
     foo:
       type: string

# Overriding the required properties
OtherModel:
  properties: *base-model-properties
  required: [foo]

# Extending with other properties
YesAnotherModel:
  properties:
    <<: *base-model-properties
    bar:
      type: integer

在您的情况下，您可以使用TaskForPost作为基本模型：

definitions:
  TaskForPost:
    type: object
    properties: &BASE-TASK-PROPERTIES
      task_list_id:
        type: integer
      title:
        type: string
      display_order:
        type: integer
      notes:
        type: string
      due:
        type: integer
      assigned_id:
        type: integer
      parent_id:
        type: integer
    required:
      - task_list_id
      - title
      - display_order

TaskForPatch会将基本模型的属性（别名BASE-TASK-PROPERTIES）与其他一些属性结合起来：

  TaskForPatch:
    type: object
    properties: &TASK-PATCH-PROPERTIES
      <<: *BASE-TASK-PROPERTIES
      completor_id:
        type: integer
        description: The SQL ident of the Person who completed this task.
      created:
        type: integer
        description: The UTC epoch time this Task was created.
      completed:
        type: integer
        description: The UTC epoch time this Task was completed.
    minProperties: 1

TaskForGet会重复使用TaskForPatch的属性（别名为TASK-PATCH-PROPERTIES）并添加额外的属性ident：

  TaskForGet:
    type: object
    properties:
      <<: *TASK-PATCH-PROPERTIES
      ident:
        type: integer
        description: The SQL ident of the Task object
    required:
      - ident
      - title
      # etc.

如果指定了completed，那么还应该指定completor_id（我正好在PATCH方法的注释中指定了这个。

Swagger模型不支持属性依赖性。这只能在操作说明或模型说明中口头记录。

^脚注锚点是built-in feature of YAML 1.2，但合并键不是 - 它们是extra feature解析器可以选择实现（或不是）。但是在某些实现中甚至可能不完全支持锚点。

Swagger编辑器对象属性

GET

POST

PATCH

1 个答案: