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使用另外的例子。