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

Posted 2023-03-08

【中文标题】带有可选字段的 serverless-aws-documentation 模型定义？

【英文标题】：serverless-aws-documentation model definitions with optional fields?

【发布时间】：2018-04-28 07:16:28

【问题描述】：

我想定义请求和响应模型。我将无服务器框架与 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 文件感到满意。

【参考方案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.

【讨论】：

您可以使用插件npmjs.com/package/serverless-reqvalidator-plugin（我写的）创建和启用请求验证器，因为目前还没有开箱即用的功能

【参考方案2】：

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

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