hidekazu-konishi.com

OpenAPI API Gateway Import Linter Tool - Validate OpenAPI Definitions for AWS API Gateway REST and HTTP APIs

First Published: 2026-04-19
Last Updated: 2026-04-19

Features

• Client-Side Processing: All linting runs locally in your browser; OpenAPI definitions never touch a server.
• Auto Format Detection: YAML and JSON are detected automatically; format indicator shows which parser was used.
• REST / HTTP API Aware: Target selector toggles rules that only apply to API Gateway v1 (REST) or v2 (HTTP).
• AWS Extension Checks: Validates x-amazon-apigateway-integration, -authorizer, -request-validator(s), -binary-media-types, -cors, -gateway-responses, and -api-key-source.
• Path Parameter Integrity: Flags {param} placeholders that are missing a matching parameters entry with in: path and required: true.
• HTTP API Non-Support Detection: Highlights features (request validators, API key source, Usage Plan extensions, binary media types) that are not supported on HTTP API.
• Five Sample Presets: REST Lambda proxy, REST Lambda authorizer, HTTP API JWT, Warnings-only, and Errors examples load instantly.
• Debounced Auto-Lint: Linting runs automatically 400 ms after typing stops.
• Copyable Report: Copy all findings to the clipboard as plain text for pasting into PRs, tickets, or chat.
• Mobile Friendly: Responsive layout works on phones and tablets.
• Offline Capable: Once loaded, the tool continues to work without an internet connection.

How to Use

1. Select the target API Gateway type (REST API or HTTP API) that you intend to import the definition into.
2. Paste an OpenAPI spec into the textarea, drop a .yaml / .yml / .json file onto the drop zone, or click one of the five sample preset buttons.
3. The format indicator shows whether YAML or JSON was detected.
4. Lint runs automatically after a short pause, or you can click Run Lint to trigger it immediately.
5. Review the findings table: each row lists Level (error / warning / info), Rule ID, Path (dot notation, e.g. paths./items/{id}.get.x-amazon-apigateway-integration), and Message.
6. Use Copy Report to copy all findings as text, or Clear All to reset the tool.
7. Toggle the API Gateway target and re-lint to see how the rules differ between REST and HTTP API.

Rules Implemented

• PARSE: YAML or JSON parse error (single finding, halts further checks).
• OAS1001: openapi must be 3.0.x or 3.1.x; swagger: "2.0" is accepted for REST but flagged as a warning for HTTP API (v2) which requires OpenAPI 3).
• OAS1002: info, info.title, and info.version are required.
• OAS1003: paths is required and must be an object.
• OAS2001: Every {paramName} path template must have a matching parameters entry with in: path and required: true (declared at path-item or operation level).
• OAS2002: Duplicate operationId across operations.
• AWS3001: Operation is missing x-amazon-apigateway-integration (warning).
• AWS3002: Integration missing required fields (type, httpMethod, uri, passthroughBehavior for REST) or type not in {http, http_proxy, aws, aws_proxy, mock}.
• AWS3003: type: aws_proxy with a Lambda-style uri but httpMethod is not POST (info).
• AWS3004: Operation references an x-amazon-apigateway-request-validator that is not defined in the top-level x-amazon-apigateway-request-validators.
• AWS3005: x-amazon-apigateway-authorizer missing required fields for its type (token / request / cognito_user_pools / jwt).
• AWS3006: x-amazon-apigateway-binary-media-types must be an array of strings; present on HTTP API is flagged as a warning.
• AWS3007: x-amazon-apigateway-cors is HTTP-API-only; flagged on REST API.
• AWS3008: x-amazon-apigateway-gateway-responses structure check.
• AWS4001: HTTP API only: flags use of x-amazon-apigateway-request-validator(s), -api-key-source, and Usage-Plan-related extensions that are not supported on API Gateway v2.

Important Notes

• This static linter does not replace aws apigateway import-rest-api --validate-only or aws apigatewayv2 import-api. It is a pre-flight check, not a substitute for the real import call.
• Full OpenAPI schema validation (e.g. Spectral, Stoplight) is out of scope. Only a small subset of structural rules are applied.
• External $ref references (files, URLs) are not resolved. Only inline content is inspected.
• AWS extension rules reflect publicly documented behavior and may lag behind service changes.
• Files larger than 5 MB are rejected for file drops. Very large specs may take longer to lint depending on your browser.
• Always verify with the official API Gateway import command (or CDK / SAM deployment) before production use.

References:
Tech Blog with curated related content
Web Tools Collection