63

我如何在 OpenAPI/Swagger 中定义一个字段是可选的还是必需的,默认值是什么?

4

3 回答 3

77

默认情况下,模型中的字段是可选的,除非您将它们放在required列表中。下面是一个例子 - idcategory是可选字段,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
于 2016-10-18T16:33:28.187 回答
54

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

您列出这样的必填字段:

SomeObject:
    type: object
    required:
      - name
      - fartingPower
    properties:
      name:
        type: string
      fartingPower:
        type: integer
于 2018-08-13T20:22:36.233 回答
2

另一种语法:

Response:
  type: object
  required: [id, title]
  properties:
    id:
      type: string
    title:
      type: string
于 2021-04-16T19:45:27.443 回答