GitHub - sorenjohanson/specgate: A lightweight OpenAPI validation proxy that validates HTTP responses against OpenAPI specifications in real-time.

SpecGate

A lightweight OpenAPI validation proxy that validates HTTP responses against OpenAPI specifications in real-time.

Features

Real-time validation of HTTP responses against OpenAPI 3.0 and 2.0 specifications
Remote spec loading from HTTP/HTTPS URLs with safety warnings
Multiple validation modes: strict, warn, report
Colored logging with timestamps and structured output
Lightweight: Only 3MB compressed binary
Zero configuration - works out of the box

Installation

Download Binary

Navigate to the Releases page and download the package appropriate for your OS. Unpack the included specgate binary anywhere you like.

Build from Source

git clone https://github.com/sorenjohanson/specgate.git
cd specgate
go build -ldflags="-s -w" -o specgate

Usage

Basic Usage

# Validate responses against a local OpenAPI spec
./specgate -spec openapi.yaml -upstream http://localhost:3000

# Use a remote OpenAPI spec
./specgate -spec https://api.example.com/openapi.json -upstream https://api.example.com

# Run in strict mode (returns 500 on validation errors)
./specgate -spec openapi.yaml -upstream http://localhost:3000 -mode strict

Command Line Options

Flag	Default	Description
`-spec`	`openapi.yaml`	Path or URL to OpenAPI specification
`-upstream`	`http://localhost:3000`	Upstream API URL to proxy to
`-port`	`8080`	Port for the validation proxy
`-mode`	`warn`	Validation mode: `strict`, `warn`, or `report`

Validation Modes

warn (default): Log validation errors but pass through original responses
strict: Return HTTP 500 with error details when validation fails
report: Log validation results for monitoring (soon!)

How It Works

Proxy Setup: SpecGate acts as a reverse proxy between clients and your API
Request Forwarding: All requests are forwarded to your upstream API unchanged
Response Validation: JSON responses are validated against your OpenAPI v2.0 or v3.0 spec (note: SpecGate uses kin-openapi behind the scenes, 3.1 support is tracked here)
Logging: Validation results are logged with colored output for easy monitoring
Error Handling: Based on the mode, invalid responses are either logged or replaced with errors

Client → SpecGate (validation) → Your API
       ←         (logging)     ←

Examples

Development Workflow

# Start your API server
./your-api-server &

# Run SpecGate to validate responses during development
./specgate -spec api-spec.yaml -upstream http://localhost:3000 -mode strict

# Make requests through the proxy
curl http://localhost:8080/api/users

Production Monitoring

It's possible to use SpecGate in production, but it requires re-routing existing requests through the proxy, like in development. Also, please do not use -mode strict in production. This will most likely break your API and increase support overhead!

Please share any issues you find if you do end up using SpecGate in production.

./specgate \
  -spec https://api.example.com/openapi.json \
  -upstream https://api.example.com \
  -port 8080

Remote Spec with Safety Check

When using a remote spec that doesn't match your upstream URL, SpecGate will warn you:

./specgate -spec https://docs.example.com/spec.json -upstream https://api.other.com
# WARNING: spec URL (https://docs.example.com) does not match upstream URL (https://api.other.com)
# Do you want to continue? (y/N):

Configuration

Logging

SpecGate provides colored, structured logging:

🔴 ERROR: Validation failures, critical issues
🟡 WARN: Undocumented endpoints, non-critical issues
🟢 INFO: Startup information, general status

Contributing

We welcome contributions! Please see CONTRIBUTING.md for detailed guidelines on:

Setting up your development environment
Installing Go and required tools
Development workflow and coding standards
Testing and building procedures
Pull request process

License

This project is licensed under the GNU General Public License v3.0 - see LICENSE for info.

Acknowledgments

Built with kin-openapi for OpenAPI validation
Uses Go's standard library log/slog for structured logging