Определения модели serverless-aws-документации с необязательными полями?

Question

Я хочу определить модели запросов и ответов. Я использую Serverless Framework с AWS, и все, что я вижу, рекомендует использовать Serverless-AWS-документацию

README говорит, что мне нужно иметь эту строку в custom.documentation.models.MODELNAME

schema: ${file(models/error.json)}

Но у них нет примера файла models/error.json использовать в качестве базовой линии.

В реальном примере serverless.yml у них есть такое определение:

-
  name: DoSomethingRequest
  contentType: "application/json"
  schema:
    type: array
    items:
      type: string

Это не дает достаточно деталей для того, что я пытаюсь сделать.

---

Моя цель - определить схему для массива строковых объектов, сообщения и кода состояния. Однако сообщение и код состояния не являются обязательными. Они также могут быть частью других моделей, и, если возможно, я бы не хотел повторять их определение для каждой модели.

Моя текущая попытка:

-
  name: ReturnArrayResponse
  contentType: "application/json"
  schema:
    type: array
    itemsArray:
      type: string
    message:
      type: string
    statusCode:
      type: number

Я думаю, что это будет делать то, что я хочу, но как я могу иметь message а также statusCode быть необязательным и повторить эти два пункта в моих других моделях?

Я был бы счастлив либо с yml-решением, которое я могу поместить в свой файл serverless.yml, либо с json-файлом, на который я могу сослаться.

Answer 1

Включая файл

В приведенном примере error.json может содержать любую допустимую схему. Так что все так просто, как это хорошо:

{"type":"object","properties":{"message":{"type":"string"}}}

Также можно включить такие атрибуты, как $schema а также title:

{
  "$schema" : "http://json-schema.org/draft-04/schema#",
  "title" : "Error Schema",
  "type" : "object",
  "properties" : {
    "message" : { "type" : "string" },
    "statusCode": { "type": "number" },
    "itemsArray": {
        "type": "array",
        "items": {
            "type": "string"
        }
    }
  }
}

Это особенно удобно, когда у вас уже есть модели, определенные в AWS, но у вас нет серверного yaml для их создания. Вы можете просто скопировать схему из консоли AWS, вставить json в файл и использовать schema: ${file()} Синтаксис, упомянутый в вопросе. Насколько я могу сказать, все, что вы можете заставить консоль AWS принять, будет работать.

DRY

Я не знаю, как ссылаться на модели из других моделей в файле без сервера, но вы можете использовать тот же подход, что и авторы плагинов, и просто поместить все, что вам нужно, для повторного использования вне models и где-то легче использовать повторно. Авторы плагинов используют commonModelSchemaFragments,

Итак, если у вас есть несколько фрагментов, например, так:

  commonModelSchemaFragments:
    # defining common fragments means you can reference them with a single line
    StringArrayFragment:
        type: array
        items:
          type: string
    HttpResponse:
      type: object
      properties:
        message:
          type: string
        statusCode:
          type: number     

Вы можете ссылаться на эти фрагменты в моделях следующим образом:

  - 
    name: HttpStatusResponse
    contentType: "application/json"
    schema:
      type: object
      properties:
          serverResponse: 
            ${self:custom.commonModelSchemaFragments.HttpResponse}
          messageArray: 
            ${self:custom.commonModelSchemaFragments.StringArrayFragment}

Маркировка атрибутов необязательна

Вы можете сделать это, пометив атрибуты как required, Просто предоставьте список всех атрибутов, кроме тех, которые вы хотите использовать не обязательно. Схема JSON для этого выглядит следующим образом:

{
    "type": "object",
    "required": ["message"],
    "properties": {
        "optionalMessage": {
            "type": "string"
        },
        "message": {
            "type": "string"
        }
    }
}

который вы бы построили, используя yaml в своем файле без сервера:

  -
    name: OptionalResponse
    contentType: "application/json"
    schema:
      type: object
      required: 
      - "message"
      properties:
        message:
          type: string
        optionalMessage:
          type: string

Примечание о подтверждении запроса

Маркировка атрибутов required или же optional имеет значение только если включена проверка тела запроса:

Я не знаю, как включить проверку запросов, используя какой-либо специальный серверный синтаксис. Похоже, вы можете сделать это в resources раздел, но я не пробовал. Источник

Answer 2

Просто предположение (опубликовав его как ответ для сохранения форматирования) - ваша сущность верхнего уровня в схеме должна быть objectне array, что-то вроде этого:

    schema:
      type: object
      properties:
        items:
          type: array
          items:
            type: string
        message:
          type: string
        statusCode:
          type: number