如何使用 JSON Schema 和 Swagger 在 API Gateway 模型中声明多个类型的属性？

Question

根据 AWS 文档，API Gateway 中的模型支持 JSON Schema 语法，但是，它们导出为 Swagger OpenAPI 规范，其中 Swagger 规范并不完全支持许多有效的 JSON Schema 结构。

我希望我的 API 网关模型有一组可选文本字段，例如

message

，但当定义为

时

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string"
    }
  }

}

并且启用正文验证后，当消息为空字符串或丢失时，它会拒绝此模型。即使

message

未包含在必填字段列表中

，它也会这样做

  "required": [
      "message"
    ],

深入研究后，我发现要允许空/空字符串值，必须将

null

类型添加到属性类型列表中，例如：

{
    "type": ["null", "string"]
}

但是，这仍然无法与 API Gateway 一起使用，也不能正确导出为 Swagger 规范 YAML。

有没有办法用 API Gateway 和 Swagger 来解决这个问题？

Answer 1

Helen 提到，Swagger 不支持多种类型，也不支持 null 作为类型。这可能会阻止您的第一种方法使用 swagger 导入/导出。

但是，内部 API 网关模型支持确实使用 JSON 架构，并且即使导入/导出不起作用，也可能起作用。我建议您尝试通过 API Gateway 控制台或 API Gateway CLI 输入您的模型。

Answer 2

这对我来说适用于 Open API 3.0 和 API Gateway、CDK Typescript：

        const model = props.rootApi.dataApi.addModel(`${props.appEnv}-name-${props.apiVersion}`, {
            contentType: 'application/json',
            modelName: `ItemResponseModel${props.apiVersion}`,
            schema: {
                schema: aws_apigateway.JsonSchemaVersion.DRAFT4,
                title: 'ItemResponse',
                type: aws_apigateway.JsonSchemaType.ARRAY,
                properties: {
                    time: { type: aws_apigateway.JsonSchemaType.STRING },
                    endTimestamp: { type: aws_apigateway.JsonSchemaType.STRING },
                    hours: { type: [aws_apigateway.JsonSchemaType.INTEGER, aws_apigateway.JsonSchemaType.NULL] },
                    watts: { type: [aws_apigateway.JsonSchemaType.NUMBER, aws_apigateway.JsonSchemaType.NULL] },
                },
                required: [
                    'time',
                    'endTimestamp',
                    'hours',
                    'watts',
                ],
            },
        })

参考https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.Model.html