REST API 具有“必需”响应 属性 是什么意思？

What does it mean for a REST API to have a `required` response property?

学习 REST API 秒并关注 https://apihandyman.io/writing-openapi-swagger-specification-tutorial-part-2-the-basics/。

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

API 将 return firstname、lastname 和 username，但使用 [= 仅需要 username 16=] 关键字。这对我来说没有意义。缺少 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.

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

更多信息以及指向以下规范相关部分的指针：

  • 响应对象的 required 属性 列表的语义被定义为 OpenAPI 规范的 Schema Object 部分的一部分。那里说模式对象 "is based on the JSON Schema Specification Draft 4 and uses a predefined subset of it".

  • 在JSON Schema Validation规范的required验证关键字的相应部分中，其语义定义如下：

5.4.3. required

5.4.3.1. Valid values

The value of this keyword MUST be an array. This array MUST have at least one element. Elements of this array MUST be strings, and MUST be unique.

5.4.3.2. Conditions for successful validation

An object instance is valid against this keyword if its property set contains all elements in this keyword's array value.