Что означает, что для REST API требуется свойство `required` response?

Question

Изучение API REST и я следую 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. Там говорится, что объект схемы «основан на проекте 4 спецификации спецификации JSON и использует предопределенное подмножество».

• В соответствующем разделе, посвященном required проверки ключевого слова в описании JSON Schema Validation его семантика определяется следующим образом:

5.4.3. требуется

5.4.3.1. Допустимые значения

Значение этого ключевого слова ДОЛЖНО быть массивом. Этот массив ДОЛЖЕН иметь в наименее один элемент. Элементы этого массива ДОЛЖНЫ быть строками, и ДОЛЖНЫ быть уникальными.

5.4.3.2. Условия для успешной проверки

Экземпляр объекта действителен против этого ключевого слова, если его свойство установлено содержит все элементы в массиве этого ключевого слова.

• Вы найдете другие примеры того, как required можно использовать ключевое слово в examples section спецификации JSON Schema или Part 5, Section 2.2 учебника вы следуете.