REST API具有"required"响应属性意味着什么？

Question

了解REST API并遵循https://apihandyman.io/writing-openapi-swagger-specification-tutorial-part-2-the-basics/.

API可以接收两个参数:username和bla,但只有username使用required关键字才需要.这对我来说很有意义.

API将返回firstname,, lastname和username,但仅username在使用required关键字时才需要.这对我来说没有意义.缺少required关键字是否表明有时可能不需要其他两个？影响他们是否有什么影响？

paths:
  /persons/{username}:
    get:
      summary: Gets a person
      description: Returns a single person for its username.
      parameters:
        - name: username
          in: path
          required: true
          description: The person's username
          type: string
        - name: bla
          in: query
          description: bla bla bla
          type: string
      responses:
        200:
          description: A Person
          schema:
            required:
              - username
            properties:
              firstName:
                type: string
              lastName:
                type: string
              username:
                type: string
        404:
          description: The Person does not exists.

Answer 1

你的解释是正确的.如果响应对象的required属性列在属性列表中,则响应对象中必须存在该属性才能使其有效,这与required参数对象中的字段非常相似.响应中是否包含非必需属性取决于应用程序的业务逻辑.

更多信息,指向以下规范的相关部分:

• required响应对象的属性列表的语义被定义为OpenAPI规范的Schema Object部分的一部分.它说模式对象"基于JSON模式规范草案4并使用它的预定义子集".

• 在JSON模式验证规范的required验证关键字的相应部分中,其语义定义如下:

5.4.3.需要

5.4.3.1.有效值

该关键字的值必须是一个数组.这个数组必须至少有一个元素.这个数组的元素必须是字符串,并且必须是唯一的.

5.4.3.2.成功验证的条件

如果对象实例的属性集包含此关键字的数组值中的所有元素,则该对象实例对此关键字有效.

• 您将在JSON模式规范required的示例部分或您正在学习的教程的第5部分第2.2 节中找到有关如何使用关键字的更多示例.