amazon-web-services - 带有可选字段的serverless-aws-documentation模型定义？

Question

我想定义请求和响应模型。我将无服务器框架与AWS结合使用，看到的所有内容都建议使用serverless-aws-documentation

自述文件说我需要在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是可选的并在其他模型中重复这两项呢？

我对可以放入serverless.yml文件或可以引用的json文件的yml解决方案感到满意。

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控制台接受。

干燥

我不知道从无服务器文件中的其他模型中引用模型的方法，但是您可以使用与插件作者相同的方法，并且只需将需要重用的所有内容放在 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部分中执行此操作，但是我还没有尝试过。 Source。