Skip to content

oastools

oastools

A complete, self-contained OpenAPI toolkit for Go — parse, validate, fix, convert, diff, join, generate, and build OpenAPI specs (2.0–3.2) with minimal dependencies.

CI: Go codecov Go Reference License: MIT

Get Started

📦 Go Library

Import oastools packages into your Go application for parsing, validation, conversion, code generation, and more. All packages use a consistent functional options API.

result, _ := parser.ParseWithOptions(parser.WithFilePath("api.yaml"))
vResult, _ := validator.ValidateWithOptions(validator.WithDocument(result))

→ Developer Guide — Complete library usage with examples for all 12 packages

🖥️ CLI / CI/CD

Run oastools from the terminal, in shell scripts, or as a CI/CD pipeline step. Supports file and URL inputs, stdin/stdout piping, and JSON output for machine consumption.

oastools validate openapi.yaml
oastools diff --breaking --format json v1.yaml v2.yaml | jq

→ CLI Reference — All commands, flags, and output formats

🤖 MCP Server

Connect oastools to Claude Code, Cursor, VS Code, or any MCP-compatible AI agent. All 17 tools are available over stdio via the Model Context Protocol.

oastools mcp  # Start the MCP server

→ MCP Server Guide — Setup and tool reference → Claude Code Plugin — One-command setup for Claude Code

🌐 Try it Online

No installation required — use oastools directly in your browser:

oastools.robnrob.com — Validate, convert, diff, fix, join, and apply overlays.

What's Included

Package Description Try
parser Parse & analyze OAS files from files, URLs, or readers
validator Validate specs with structural & semantic checks 🌐
fixer Auto-fix common validation errors 🌐
httpvalidator Validate HTTP requests/responses against OAS at runtime
converter Convert between OAS 2.0 and 3.x 🌐
joiner Merge multiple OAS documents with schema deduplication 🌐
overlay Apply OpenAPI Overlay v1.0.0 with JSONPath targeting 🌐
differ Detect breaking changes between versions 🌐
generator Generate Go client/server code with security support
builder Programmatically construct OAS documents with deduplication
walker Traverse OAS documents with typed handlers and flow control
oaserrors Structured error types for programmatic handling

All packages include comprehensive documentation with runnable examples. See individual package pages on pkg.go.dev for API details.

Why oastools?

→ Full details

Minimal Dependencies

Only go.yaml.in/yaml, golang.org/x/tools, golang.org/x/text, and the MCP Go SDK at runtime. No sprawling dependency trees.

Battle-Tested

8,000+ tests validated against 10 production APIs — Stripe, GitHub, Discord, Microsoft Graph (34MB), and more. Spans OAS 2.0 through 3.1, JSON and YAML, 20KB to 34MB.

Performance

Pre-parsed workflows are 11–150x faster. JSON marshaling optimized for 25-32% better performance. 340+ benchmarks track regressions. See Benchmarks.

Enterprise-Ready

Structured errors with errors.Is()/errors.As(), configurable resource limits, pluggable HTTP clients, deterministic output ordering, and generated DeepCopy() methods for safe document mutation.

Installation

CLI

brew install erraggy/oastools/oastools                   # Homebrew (macOS/Linux)
go install github.com/erraggy/oastools/cmd/oastools@latest  # Go install

Pre-built binaries for macOS, Linux, and Windows on the Releases page.

Library

go get github.com/erraggy/oastools@latest

Requires Go 1.24+.

Examples

Explore complete, runnable examples demonstrating the full oastools ecosystem:

Category Examples Time
Getting Started Quickstart, Validation Pipeline 2-5 min
Workflows Validate & Fix, Version Conversion, Multi-API Merge, Breaking Changes, Overlays, HTTP Validation 3-5 min each
Programmatic Builder with ServerBuilder 5 min
Code Generation Petstore (stdlib & chi router) 10 min
Walker API Statistics, Security Audit, Public API Filter 3-5 min each

See all examples for the full list.

Supported OpenAPI Versions

Version Specification
2.0 (Swagger) spec
3.0.0 – 3.0.4 spec
3.1.0 – 3.1.2 spec
3.2.0 spec

Automatic format detection and preservation (JSON/YAML), external reference resolution, JSON Pointer array index support, and full JSON Schema Draft 2020-12 compliance for OAS 3.1+.

Contributing

  1. Fork and create a feature branch
  2. Run make check before committing
  3. Follow conventional commits (e.g., feat(parser): add feature)
  4. Submit a PR

See WORKFLOW.md for guidelines.

License

MIT

All code generated by Claude Code using claude-4-5-sonnet/opus with minor edits and full control by @erraggy