如何在 OpenAPI/Swagger 中指定字段是可选的还是必需的？

默认情况下，模型中的字段是可选的，除非您将它们放在 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

除非根据需要标记，否则字段是可选的。

您可以像下面这样列出所需的字段:

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

另一种语法:

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