oastools

package module
v1.51.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 16, 2026 License: MIT Imports: 2 Imported by: 0

README

oastools - for validating, parsing, fixing, converting, diffing, joining, and building specs

A complete, self-contained OpenAPI toolkit for Go with minimal dependencies.

Go Report Card codecov Go Reference Try it Online

Parse, validate, fix, convert, diff, join, generate, and build OpenAPI specs (2.0–3.2) — all in one tool.

What It Does

Spec Lifecycle — parser · validator · fixer · converter
Multi-Spec Ops — joiner · differ · overlay
Code & Query — generator · builder · walker
Runtime — httpvalidator · oaserrors

12 packages covering the full OpenAPI lifecycle. See full details →

Highlights

  • 📦 Minimal Dependencies — Only go.yaml.in/yaml, golang.org/x/tools, golang.org/x/text, and the MCP Go SDK at runtime
  • ✅ Battle-Tested — 8,000+ tests against 10 production APIs (Stripe, GitHub, Discord, MS Graph 34MB)
  • ⚡ Performance — Pre-parsed workflows 11–150x faster; 340+ benchmarks
  • 📋 OAS 2.0–3.2 — Full JSON Schema Draft 2020-12 for OAS 3.1+; automatic format detection and preservation
  • 🤖 AI-Ready — Built-in MCP server exposes all capabilities to LLM agents
  • 🌐 Try Online — oastools.robnrob.com — no install required

Quick Start

CLI

oastools validate openapi.yaml                          # Validate a spec
oastools convert -t 3.0.3 swagger.yaml -o openapi.yaml  # Convert versions
oastools diff --breaking v1.yaml v2.yaml                 # Detect breaking changes
oastools fix api.yaml -o fixed.yaml                      # Auto-fix errors
oastools join -o merged.yaml base.yaml ext.yaml          # Merge specs
oastools generate --client --server -o ./gen -p api openapi.yaml  # Generate Go code

Library

// Parse, validate, and fix — consistent functional options API
result, _ := parser.ParseWithOptions(parser.WithFilePath("api.yaml"))
vResult, _ := validator.ValidateWithOptions(validator.WithDocument(result))
fResult, _ := fixer.FixWithOptions(fixer.WithDocument(result))

Full library guide →

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+.

Documentation

📚 Documentation Site — Guides, examples, and package deep dives

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

🤖 MCP Server — LLM agent integration via Model Context Protocol

📦 API Reference — Go package documentation with runnable examples

Contributing

Fork, branch, make check, conventional commits. See WORKFLOW.md for the full process.

License

MIT

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

Documentation

Overview

Package oastools provides tools for parsing, validating, fixing, converting, joining, comparing, generating code from, and building OpenAPI Specification (OAS) documents from OAS 2.0 through OAS 3.2.0.

The library consists of twelve packages:

For installation, CLI usage, and examples, see: https://github.com/erraggy/oastools

For detailed API documentation and examples, see the individual package pages.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BuildInfo added in v1.17.2 

func BuildInfo() string

BuildInfo returns a formatted string with all build metadata

func BuildTime added in v1.17.2 

func BuildTime() string

BuildTime returns the build timestamp or 'unknown' if run from source

func Commit added in v1.17.2 

func Commit() string

Commit returns the git commit hash or 'unknown' if run from source

func GoVersion added in v1.17.2 

func GoVersion() string

GoVersion returns the Go version used to build the binary

func UserAgent 

func UserAgent() string

UserAgent returns the User-Agent string to use

func Version 

func Version() string

Version returns the compiled version or 'dev' if run from source

Types

This section is empty.

Source Files

View all Source files

Directories

Path Synopsis
Package builder provides programmatic construction of OpenAPI Specification documents.
 Package builder provides programmatic construction of OpenAPI Specification documents.
cmd
oastools command
oastools/commands
Package commands provides CLI command handlers for oastools.
 Package commands provides CLI command handlers for oastools.
Package converter provides version conversion for OpenAPI Specification documents.
 Package converter provides version conversion for OpenAPI Specification documents.
Package differ provides OpenAPI specification comparison and breaking change detection.
 Package differ provides OpenAPI specification comparison and breaking change detection.
Package fixer provides automatic fixes for common OpenAPI Specification validation errors.
 Package fixer provides automatic fixes for common OpenAPI Specification validation errors.
Package generator provides Go code generation from OpenAPI Specification documents.
 Package generator provides Go code generation from OpenAPI Specification documents.
Package httpvalidator validates HTTP requests and responses against OpenAPI specifications.
 Package httpvalidator validates HTTP requests and responses against OpenAPI specifications.
integration
corpus
Package corpus provides integration tests that exercise cross-package workflows using real-world OpenAPI specifications from the corpus.
 Package corpus provides integration tests that exercise cross-package workflows using real-world OpenAPI specifications from the corpus.
internal
codegen/decode command
Package main generates decodeFromMap methods for parser package types.
 Package main generates decodeFromMap methods for parser package types.
codegen/deepcopy command
Package main generates DeepCopy methods for parser package types.
 Package main generates DeepCopy methods for parser package types.
corpusutil
Package corpusutil provides utilities for loading and managing the integration test corpus of real-world public OpenAPI specifications.
 Package corpusutil provides utilities for loading and managing the integration test corpus of real-world public OpenAPI specifications.
httputil
Package httputil provides HTTP-related validation utilities and constants.
 Package httputil provides HTTP-related validation utilities and constants.
issues
Package issues provides a unified issue type for validation and conversion problems.
 Package issues provides a unified issue type for validation and conversion problems.
jsonpath
Package jsonpath provides a minimal JSONPath implementation for OpenAPI Overlay support.
 Package jsonpath provides a minimal JSONPath implementation for OpenAPI Overlay support.
maputil
mcpserver
Package mcpserver implements an MCP (Model Context Protocol) server that exposes oastools capabilities as MCP tools over stdio.
 Package mcpserver implements an MCP (Model Context Protocol) server that exposes oastools capabilities as MCP tools over stdio.
naming
Package naming provides shared case conversion utilities for oastools packages.
 Package naming provides shared case conversion utilities for oastools packages.
options
Package options provides shared utilities for option validation across packages.
 Package options provides shared utilities for option validation across packages.
pathutil
Package pathutil provides efficient path building utilities for OpenAPI document traversal.
 Package pathutil provides efficient path building utilities for OpenAPI document traversal.
schemautil
Package schemautil provides utilities for working with OpenAPI schema types.
 Package schemautil provides utilities for working with OpenAPI schema types.
severity
Package severity provides severity level constants and utilities for issues reported by validator, converter, differ, and generator packages.
 Package severity provides severity level constants and utilities for issues reported by validator, converter, differ, and generator packages.
stringutil
testutil
Package joiner provides joining for multiple OpenAPI Specification documents.
 Package joiner provides joining for multiple OpenAPI Specification documents.
Package oaserrors provides structured error types for the oastools library.
 Package oaserrors provides structured error types for the oastools library.
Package overlay provides support for OpenAPI Overlay Specification v1.0.0.
 Package overlay provides support for OpenAPI Overlay Specification v1.0.0.
Package parser provides parsing for OpenAPI Specification documents.
 Package parser provides parsing for OpenAPI Specification documents.
internal/jsonhelpers
Package jsonhelpers provides helper functions for JSON marshaling and unmarshaling with support for extension fields (x-* properties) in OpenAPI specifications.
 Package jsonhelpers provides helper functions for JSON marshaling and unmarshaling with support for extension fields (x-* properties) in OpenAPI specifications.
Package validator provides validation for OpenAPI Specification documents.
 Package validator provides validation for OpenAPI Specification documents.
Package walker provides a document traversal API for OpenAPI specifications.
 Package walker provides a document traversal API for OpenAPI specifications.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.