OpenAPI extensions for API Gateway Validator

Amazon API Gateway の OpenAPI 拡張プロパティを検証する Rust 製 CLI です。

Installation

cargo build --release

Usage

cargo run -- path/to/openapi.yaml

# security warning も CI failure として扱う場合
cargo run -- --deny-warnings path/to/openapi.yaml

検証対象ファイルの拡張子は .yaml または .yml である必要があります。デフォルトでは、DoS 対策として 10 MiB を超える入力ファイルは読み込み前に拒否します。

検証結果は以下の終了コードで返します。

• 0: schema / semantic error なし（security warning のみの場合も、通常は 0）
• 1: schema / semantic error あり、または --deny-warnings 指定時に warning あり
• 2: 引数、拡張子、ファイル読み込み、YAML パースのエラー

Sample OpenAPI files

コマンドの動作確認用に、正常系と異常系のサンプル YAML を examples/ に置いています。

# 正常系: exit code 0 で "No invalid properties found" を出力します
cargo run -- examples/valid-openapi.yaml

# 異常系: schema / semantic error を検出して exit code 1 で終了します
cargo run -- examples/invalid-openapi.yaml

# warning も CI failure として扱う挙動を確認できます
cargo run -- --deny-warnings examples/invalid-openapi.yaml

Current validation scope

現在は以下を検証します。

• root-level x-amazon-apigateway-* extensions
• path-level x-amazon-apigateway-cors and x-amazon-apigateway-any-method
• operation-level auth, authorizer, request-validator, and integration extensions
• securityDefinitions.* / components.securitySchemes.* API Gateway auth extensions
• components.x-amazon-apigateway-integrations.*

検証内容は以下です。

• 未知の x-amazon-apigateway-* 拡張プロパティ
• x-amazon-apigateway-api-key-source: HEADER, AUTHORIZER
• x-amazon-apigateway-binary-media-type: string
• x-amazon-apigateway-binary-media-types: string array
• x-amazon-apigateway-cors: origins/methods/headers, credentials, max age
• x-amazon-apigateway-documentation: object または array
• x-amazon-apigateway-endpoint-configuration.types: EDGE, REGIONAL, PRIVATE
• x-amazon-apigateway-gateway-responses: status code, response parameters, response templates
• x-amazon-apigateway-importexport-version: string
• x-amazon-apigateway-minimum-compression-size: 0 以上 10485760 以下の整数
• x-amazon-apigateway-policy: object
• x-amazon-apigateway-request-validator: string
• x-amazon-apigateway-request-validators: request validator map
• x-amazon-apigateway-tag-value: string
• x-amazon-apigateway-auth: object
• x-amazon-apigateway-authorizer: authorizer type, TTL, JWT configuration, identity/source fields
• x-amazon-apigateway-authtype: string
• x-amazon-apigateway-integration の未知のトップレベル integration プロパティ
• x-amazon-apigateway-integration.type: AWS, HTTP, MOCK, HTTP_PROXY, AWS_PROXY
• x-amazon-apigateway-integration.connectionType: INTERNET, VPC_LINK
• x-amazon-apigateway-integration.contentHandling: CONVERT_TO_BINARY, CONVERT_TO_TEXT
• x-amazon-apigateway-integration.passthroughBehavior: WHEN_NO_MATCH, WHEN_NO_TEMPLATES, NEVER
• x-amazon-apigateway-integration.timeoutInMillis: 50 以上 29000 以下の整数
• x-amazon-apigateway-integration.tlsConfig.insecureSkipVerification: boolean
• x-amazon-apigateway-integration.requestParameters のキー prefix: integration.request.
• x-amazon-apigateway-integration.responses.*.responseParameters のキー prefix: method.response.header.

Validation levels

この validator の対応状況は、AWS と同等の完全 validation ではなく、以下のレベルで表現します。

• Basic: 型、enum、prefix、範囲、未知プロパティを検証する
• Semantic: 複数プロパティ間の整合性や必須項目を検証する
• Security lint: AWS には import できる可能性があるが、レビューすべき危険設定を warning として検出する

Area	Basic	Semantic	Security lint
Root API Gateway extensions	✅	Partial	Partial
Path/operation API Gateway extensions	✅	Partial	Partial
Authorizer extensions	Partial	Partial	Partial
Resource policy	Object only	❌	Wildcard warning
Request validators	✅	❌	Disabled validator warning
CORS	✅	❌	Wildcard/credentials warning
Integration extensions	✅	Partial	TLS verification warning

Supported / partially validated properties

https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/api-gateway-swagger-extensions.html

The following properties are parsed and at least partially validated. See Validation levels above for the distinction between basic validation, semantic validation, and security linting.

• x-amazon-apigateway-any-method
• x-amazon-apigateway-cors
• x-amazon-apigateway-api-key-source
• x-amazon-apigateway-auth
• x-amazon-apigateway-authorizer
• x-amazon-apigateway-authtype
• x-amazon-apigateway-binary-media-type
• x-amazon-apigateway-documentation
• x-amazon-apigateway-endpoint-configuration
• x-amazon-apigateway-gateway-responses
• x-amazon-apigateway-gateway-responses.gatewayResponse
• x-amazon-apigateway-gateway-responses.responseParameters
• x-amazon-apigateway-gateway-responses.responseTemplates
• x-amazon-apigateway-importexport-version
• x-amazon-apigateway-integration
• x-amazon-apigateway-integrations
• x-amazon-apigateway-integration.requestTemplates
• x-amazon-apigateway-integration.requestParameters
• x-amazon-apigateway-integration.responses
• x-amazon-apigateway-integration.response
• x-amazon-apigateway-integration.responseTemplates
• x-amazon-apigateway-integration.responseParameters
• x-amazon-apigateway-integration.tlsConfig
• x-amazon-apigateway-minimum-compression-size
• x-amazon-apigateway-policy
• x-amazon-apigateway-request-validator
• x-amazon-apigateway-request-validators
• x-amazon-apigateway-request-validators.requestValidator
• x-amazon-apigateway-tag-value

Security and dependency tracking

• Dependency security checks are configured in GitHub Actions with cargo audit and cargo deny.
• YAML parsing uses serde_yaml_ng; parser migration notes are tracked in docs/serde-yaml-migration.md.