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 Schema Validation规范的required验证关键字的相应部分中，其语义定义如下：

  

5.4.3。需要

     

5.4.3.1。有效值

     

此关键字的值必须是数组。这个数组必须有   至少一个元素。这个数组的元素必须是字符串，并且必须是   唯一的。

     

5.4.3.2。成功验证的条件

     

如果对象实例的属性设置，则该对象实例对此关键字有效   包含此关键字的数组值中的所有元素。

• 您可以找到有关required关键字如何在JSON模式规范的examples section或您正在关注的教程的Part 5, Section 2.2中使用的更多示例。