带有可选字段的无服务器 aws 文档模型定义？

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 是可选的并在我的其他模型中重复这两项呢？

我很乐意将 yml 解决方案放入我的 serverless.yml 文件或我可以参考的 json 文件。

Answer 1

只是猜测（将其作为答案发布以保留格式）- 架构中的顶级实体应该是 object，而不是 array，如下所示：

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

Answer 2

包括一个文件

在给出的示例中，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.

带有可选字段的无服务器 aws 文档模型定义？

serverless-aws-documentation model definitions with optional fields?

amazon-web-services

aws-api-gateway

serverless-framework

serverless-plugins