swagger 在不使用API ID的情况下引用API网关中的外部模型

qxgroojn  于 2022-11-06  发布在  其他
关注(0)|答案(2)|浏览(141)

我正在使用JSON Schema编写一个API网关模型,并使用无服务器框架部署它。

"$ref": "https://apigateway.amazonaws.com/restapis/{restapi_id}/models/{model_name}"

问题是,这需要知道API ID。在我的例子中,模型将在多个API中重用,每个API都有自己的ID,因此在模型中硬编码ID没有意义。
有没有办法在不使用API ID的情况下引用外部模型,或者在部署过程中将API ID注入到模型中?

uz75evzq

uz75evzq1#

您可以导出模型并将其保存在配置文件中以供以后使用。这并不一定是您想要的,但它为您提供了对标准模型的版本控制,并允许您跨服务使用它们。
例如,使用serverless-aws-documentation
在无服务器.yml中

custom:
  documentation:
    models: ${file(./conf/api/methodResponse/models.yml):models}

plugins:
  - serverless-aws-documentation

在引用的模型中。yml:

models:
  -
    name: EmptyModel
    contentType: "application/json"
    schema:
      "$schema": "http://json-schema.org/draft-04/schema#"
      title: "Empty/Passthrough Response"
      type: object

请注意,“$schema”字段似乎是可选的,我相信,至少我的测试在部署和运行时没有它。我只是保留了它,因为AWS的模板使用它。
这将给予你对模型的本地控制。这将意味着你需要做一些额外的工作来同步堆栈之间的模型。
现在,如果您希望通过引用而不是通过重新部署来使用另一个服务中的现有模型,我不完全确定这是否可行。CloudFormation Model对象似乎只能通过它们的模型名称来标识,每次只能与一个ApiGatewayRestApi对象关联。当我尝试在堆栈中部署相同的模型名称时,它很高兴地强制执行,旧的模型保持不变。也许我还遗漏了什么?

kjthegm6

kjthegm62#

  • 更新:我最初发布的解决方案在某些情况下有效,但在其他情况下无效。我现在发布了一个解决方案,通常会工作(而且简单得多)。*

我刚刚遇到了同样的问题,如何在那些模型引用中保持API ID不被硬编码。这个问题已经有点老了,但是因为我花了几个小时才找到答案,我将它发布在这里以供后人参考。
假设您有一个名为 CreateUserRequest 的请求模型,并且您希望分解出 User 模式,然后将以下内容放入serverless.yaml中:

...
custom:
  documentation: 
    models:
      -
        name: "User"
        contentType: "application/json"
        schema: ${file(models/user.json)}
      -
        name: "CreateUserRequest"
        description: "User to be created"
        contentType: "application/json"
        schema:
          $ref: "{{model: User}}"

JSON模式位于 models 子文件夹的 user.json 文件中。如果你想从 user.json 文件中引用其他JSON模式,在serverless-aws-documentation中有一种特殊的方法:

{
    "$schema": "http://json-schema.org/schema#",
    "type": "object",
    "description": "A system user",
    "properties": {
        "id": {
            "type": "string",
            "title": "ID of the object"
        },
        "identity": {
            "$ref": "{{model: UserIdentity}}"
        },
        "profile": {
            "$ref": "{{model: UserProfile}}"
        }
    }
}

在无服务器的.yaml文件中,您还需要将那些被引用的模式文件称为模型。

custom:
  documentation: 
    models:
      ...
      -
        name: "UserIdentity"
        contentType: "application/json"
        schema: ${file(api-models/user-identity.json)}

      -
        name: "UserProfile"
        contentType: "application/json"
        schema: ${file(api-models/user-profile.json)}

请注意,这些JSON模式文件中的引用不是有效的JSON模式引用,因此,例如,您不能使用JSON模式验证器加载它们(至少不能直接加载)。这正是serverless-aws-documentation所期望的。如果它能够支持真正的JSON模式引用,那就更好了,但我也没有时间贡献这样的增强。

相关问题