Swagger 编辑器对象属性

Question

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

得到

GET 调用将 return 所有属于任务模型的元素。

POST

POST 调用必须指定 task_list_id、title 和 display_order。它可能包含notes、due、assigned_id和parent_id。不应从任务对象发送其他元素。

补丁

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 功能（例如 anchors (&, *) and merge keys (<<) 来避免代码重复。 这是否有效取决于您的工具是否支持这些 YAML 功能。^脚注 Swagger Editor 和 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.

If completed is specified then completor_id should also be specified (I'm OK with this one just being specified in the comments of the PATCH method.

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

^脚注锚是解析器可以选择实现（或不实现）的built-in feature of YAML 1.2, but merge keys are not -- they are an extra feature。但在某些实现中甚至可能不完全支持锚点。

Swagger 编辑器对象属性

Swagger editor object properties

swagger-2.0

swagger-editor

得到

POST

补丁