OpenAPI/Swagger 中如何指定某个字段是可选字段还是必填字段？

Question

如何在 OpenAPI/Swagger 中定义字段是可选字段还是必填字段以及默认字段是什么？

Answer 1

默认情况下，模型中的字段是可选的，除非您将它们放入

required

列表中。下面是一个示例 -

id

、

category

是可选字段，

name

是必填字段。请注意，

required

不是字段的属性，而是对象本身的属性 - 它是必需属性的列表。

type: object
required:  # List the required properties here
  - name
properties:
  id:
    type: integer
    format: int64
  category:
    $ref: '#/definitions/Category'
  name:
    type: string
    example: doggie

参考：https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger-codegen/src/test/resources/2_0/petstore.yaml#L658

如果这是请求正文的模型，您可能还需要将正文本身标记为

required

:

# swagger: '2.0'

parameters:
  - in: body
    name: body
    required: true  # <----
    schema:
      $ref: '#/definitions/Pet'

# openapi: 3.x.x

requestBody:
  required: true  # <----
  content:
    ...

要指定可选字段的默认值，您可以使用

default

属性。这是一个例子：

type: object
properties:
  huntingSkill:
    type: string
    description: The measured skill for hunting
    default: lazy

Answer 2

除非标记为必填字段，否则字段是可选的。

您列出必填字段，如下所示：

SomeObject:
    type: object
    required:
      - name
      - fartingPower
    properties:
      name:
        type: string
      fartingPower:
        type: integer

Answer 3

另一种语法：

Response:
  type: object
  required: [id, title]
  properties:
    id:
      type: string
    title:
      type: string

Answer 4

所有字段都是可选的，除非根据需要特别标记。

此外，这可能是一个重要的区别，非声明的模型字段在技术上也是可选的，无需验证即可选择。

使用

additionalProperties: false

声明，将允许您在提供附加属性的情况下抛出 400。

提供片段：

YourSchemaModel:
  type: object
  required:
  - customer_name
  - customer_signup_date
  additionalProperties: false
  properties:
    customer_name:
      type: string
    customer_signup_date:
      type: string
      format: date-time
    opted_in_for_emails:
      type: bool