如何在CloudFormation的AWS::ApiGateway::Model中保持Schema属性顺序

根本原因 #

CloudFormation和API Gateway本身没有提供强制保留Schema属性顺序的配置，该行为是服务原生设计导致的：

1. JSON规范本身不要求保留对象属性的排列顺序，CloudFormation解析模板时，会将YAML格式的Schema转换为无序JSON对象处理
2. API Gateway后端存储模型Schema时不会记录原始属性顺序，控制台展示时默认按字母序排列

该顺序变化不会影响任何业务功能：JSON Schema的校验逻辑和属性排列顺序完全无关，调整顺序后的Schema和模板定义的校验规则完全一致，不会导致请求、响应校验出错。

可选解决方案 #

如果有生成API文档、导出SDK等需要固定属性顺序的场景，可以参考以下方案：

• 改用OpenAPI规范定义全量API：将API配置、模型Schema统一写在OpenAPI文件中，作为AWS::ApiGateway::RestApi资源的Body参数传入CloudFormation模板。可以通过x-order自定义扩展字段为每个属性指定排序权重，API Gateway会识别该字段，在控制台、导出文档、生成SDK时按指定顺序展示属性。
• 若坚持使用AWS::ApiGateway::Model原生资源，可以提前将Schema序列化为保留属性顺序的JSON字符串，直接赋值给Schema字段，部分场景下API Gateway会保留字符串中的原始顺序（该方案依赖服务内部实现，不保证全区域全版本生效）。

OpenAPI方案示例 #

BWTAPI:
  Type: AWS::ApiGateway::RestApi
  Properties:
    Name: BWT API
    Body:
      openapi: 3.0.1
      info:
        title: BWT API
        version: 1.0.0
      components:
        schemas:
          PortsArray:
            $schema: 'http://json-schema.org/draft-04/schema#'
            title: 'Ports array'
            type: array
            items:
              type: object
              properties:
                Port_ID:
                  type: integer
                  x-order: 1
                Port_Name:
                  type: string
                  x-order: 2
                Province:
                  type: string
                  x-order: 3
                Lat_Actual:
                  type: integer
                  x-order: 4
                Long_Actual:
                  type: integer
                  x-order: 5
                Lat_Origin:
                  type: integer
                  x-order: 6
                Long_Origin:
                  type: integer
                  x-order: 7

内容的提问来源于stack exchange，提问作者Ironman_255