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文件的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

我不知道在无服务器文件中从其他模型中引用模型的方法，但是您可以使用与插件作者相同的方法，并且只需要在{{{{{{{ 1}}以及某个地方，它更容易重复使用。插件作者使用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}来完成此操作。只需提供所有属性的列表，除了您想要可选的属性。它的json架构如下所示：

required

你可以在无服务器文件中使用yaml构建它：

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

有关请求验证的说明

标记属性- name: OptionalResponse contentType: "application/json" schema: type: object required: - "message" properties: message: type: string optionalMessage: type: string或required仅在启用请求正文验证时才有意义：

我不知道如何使用任何特殊的无服务器语法启用请求验证。看起来您可以在optional部分执行此操作，但我还没有尝试过。 Source

Answer 2

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

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

serverless-aws-documentation模型定义和可选字段？

2 个答案: