rest - 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 的语义响应对象的属性列表被定义为 Schema Object 的一部分OpenAPI 规范的一部分。它说模式对象“基于 JSON 模式规范草案 4 并使用它的预定义子集”。

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

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.

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