如何在某些操作而不是其他操作所需的定义中创建一个字段

Question

我正在用 yaml 编写 swagger 定义。假设我有一个看起来像这样的定义。

paths:
  /payloads:
    post:
      summary: create a payload
      ...
      parameters:
      - in: body
        name: payload
        description: New payload
        required: true
        schema:
          $ref: "#/definitions/payload"
    put:
      summary: update a payload
      ...
      parameters:
      - in: body
        name: payload
        description: Updated existing payload
        required: true
        schema:
          $ref: "#/definitions/payload"
...
definitions:
  payload:
    properties:
      id:
        type: string
      someProperty:
        type: string
      ...

有没有一种方法可以表明有效负载的 ID 属性对于 PUT 操作是必需的，对于 POST 操作是可选的（或者根本不应该出现）？

Answer 1

您必须单独定义模型。

但是，您可以选择排除和差异的情况。

如果您要排除，这是最简单的情况，请创建一个包含已排除属性的模型，比如 ModelA。然后将 ModelB 定义为 ModelA 加上附加的属性:

ModelB:
  allOf:
    - $ref: "#/definitions/ModelA"
    - type: object
      properties:
        id:
          type: string

如果您要定义差异，请按照上述相同的方法，从 ModelA 中排除 id。然后将 ModelB 和 ModelC 定义为扩展 ModelA 并向它们添加 id 属性，每个都有自己的限制。请注意，JSON Schema 可以让您按照上面的原始示例对某些情况进行 "override" 定义。但是，由于它并不是真正的压倒一切，并且需要更好地理解 JSON Schema 的概念，以免犯简单的错误，我建议暂时走这条路。

Answer 2

我的方法是定义一个包含所有参数的 'abstract' 模型。然后对于每个用例，我将定义一个引用第一个用例的模型，并准确指示所需字段是什么。

paths:
  /payloads:
    post:
      summary: create a payload
      ...
      parameters:
      - in: body
        name: payload
        description: New payload
        required: true
        schema:
          $ref: "#/definitions/NewPayload"
    put:
      summary: update a payload
      ...
      parameters:
      - in: body
        name: payload
        description: Updated existing payload
        required: true
        schema:
          $ref: "#/definitions/UpdatePayload"
...
definitions:
  # This payload would be used with update requests and has no required params.
  NewPayload:
     allOf:
       - { $ref: '#definitions/PayloadProperties }
       - type: object

  # This payload would be used with update requests and require an id param.
  UpdatePayload:
     allOf:
       - { $ref: '#definitions/PayloadProperties }
       - type: object
         required: [id]

  PayloadProperties:
    properties:
      id:
        type: string
      someProperty:
        type: string
      ...

我发现此方法相当简洁，因为它不需要重复，提供关注点分离和粒度。

Answer 3

我现在遇到了同样的问题。在我的情况下，我试图覆盖模型的 requerid 块。但是没有用。 =[ 然后，我记得我们可以添加 $ref 的新属性。因此，如果您为每种方法在架构上定义重新查询的字段，它就会起作用。像这样的事情（关注每个参考所需的块）：

swagger: '2.0'
info:
  title: API
  version: 0.0.1
host: api.help.v1
basePath: /help
schemes:
- https
definitions:
  MyModel:
    description: 'Exemplo'
    type: object
    properties:
      field_1:
        type: string
      field_2:
        type: string
      field_3:
        type: string
paths:
  '/helps':
    post:
      description: ''
      summary: ''
      parameters:
        - in: body
          name: payload
          schema:
            type: object
            allOf:
            - $ref: '#/definitions/MyModel'
            required: 
            - field_1
      responses:
        '200':
          description: OK
        '400':
          description: N_OK
    put:
      description: ''
      summary: ''
      parameters:
        - in: body
          name: payload
          schema:
            type: object
            allOf: 
            - $ref: '#/definitions/MyModel'
            required: 
            - field_2
      responses:
        '200':
          description: OK
        '400':
          description: N_OK

externalDocs:
  description: Find out more about Swagger
  url: 'http://swagger.io'

哦！在 swagger 编辑器上仅通过模型视图显示：

我还没试过。但是应该可以这样定义模型。

如何在某些操作而不是其他操作所需的定义中创建一个字段

How to make a field in a definition required for some operations and not others

swagger

swagger-2.0

swagger-editor