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

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

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 файле, который я могу ссылаться.

Ответ 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, но у вас нет серверного ямла для их создания. Вы можете просто скопировать схему из консоли 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, но я этого не пробовал. Источник.

Ответ 2

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

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