oastools Examples

Complete, runnable examples demonstrating the full oastools ecosystem across parsing, validation, transformation, and code generation.

Quick Start

Time	Category	Example	Description
2 min	Getting Started	quickstart/	Parse and validate a minimal spec
5 min	Getting Started	validation-pipeline/	Complete validation with error reporting
3 min	Workflows	validate-and-fix/	Auto-fix common spec errors
3 min	Workflows	version-conversion/	Convert OAS 2.0 → 3.0.3
4 min	Workflows	multi-api-merge/	Merge microservice specs
4 min	Workflows	breaking-change-detection/	CI/CD breaking change gates
3 min	Workflows	overlay-transformations/	Environment-specific customizations
5 min	Workflows	http-validation/	Runtime request/response validation
5 min	Programmatic API	builder/	Build specs from Go code + ServerBuilder
3 min	Walker	api-statistics/	Collect API statistics in single pass
4 min	Walker	security-audit/	Audit API for security issues
3 min	Walker	vendor-extensions/	Add vendor extensions for tooling
3 min	Walker	public-api-filter/	Filter internal endpoints
4 min	Walker	api-documentation/	Generate Markdown documentation
4 min	Walker	reference-collector/	Analyze schema references
10 min	Code Generation	petstore/	Full client/server generation

Examples by Category

Getting Started

Best for first-time users learning oastools.

Example	Description
quickstart/	100-line example demonstrating parse → validate workflow
validation-pipeline/	Complete validation with source maps and severity classification

Workflow Examples

Common OpenAPI transformation patterns covering 6 packages.

Example	Package	Description
validate-and-fix/	fixer	Parse, validate, auto-fix common errors
version-conversion/	converter	Convert OAS 2.0 (Swagger) → OAS 3.0.3
multi-api-merge/	joiner	Merge specs with collision resolution
breaking-change-detection/	differ	Detect breaking changes between versions
overlay-transformations/	overlay	Apply JSONPath-based transformations
http-validation/	httpvalidator	Runtime HTTP request/response validation

Programmatic API

Build OpenAPI specifications from Go code.

Example	Package	Description
builder/	builder	Fluent API + ServerBuilder for runnable servers

Walker Examples

Document traversal patterns for analysis, mutation, and filtering.

Example	Category	Description
api-statistics/	Analysis	Collect API statistics in a single traversal pass
security-audit/	Validation	Audit API for security issues and compliance
vendor-extensions/	Mutation	Add vendor extensions for downstream tooling
public-api-filter/	Filtering	Extract public API, filter internal endpoints
api-documentation/	Reporting	Generate Markdown documentation from spec
reference-collector/	Integration	Collect schema references and detect cycles

Code Generation

Generate production-ready Go client and server code.

Example	Description
petstore/	Complete code generation with OAuth2, OIDC, chi router

Feature Matrix

Feature	quickstart	validation-pipeline	workflows	builder	walker	petstore
Parser API	✓	✓	✓	✓
Validator API	✓	✓	✓	✓
Fixer API			✓
Converter API			✓
Joiner API			✓
Differ API			✓
Overlay API			✓
HTTPValidator API			✓
Builder API				✓
ServerBuilder				✓
Walker API					✓
Source Maps		✓
Code Generation						✓
Client Generation						✓
Server Generation						✓
OAuth2 Flows						✓
OIDC Discovery						✓

Package Coverage: 11/11 packages demonstrated

OAS Version Coverage

Version	Examples
OAS 2.0 (Swagger)	petstore, version-conversion
OAS 3.0.x	quickstart, all workflows
OAS 3.2.0	builder
Any version	validation-pipeline (accepts any OAS file)

Running Examples

Each example is a standalone Go module. To run any example:

cd examples/<category>/<example-name>
go run main.go

Or build and run:

cd examples/<category>/<example-name>
go build -o example .
./example

Common Patterns

Parse-Once Optimization

All workflow examples demonstrate the parse-once pattern:

parsed, _ := parser.ParseWithOptions(parser.WithFilePath("spec.yaml"))

// Reuse for multiple operations (9-154x faster)
fixer.FixWithOptions(fixer.WithParsed(parsed))
validator.ValidateWithOptions(validator.WithParsed(parsed))

Functional Options

All packages use the functional options pattern:

result, err := converter.ConvertWithOptions(
    converter.WithFilePath("swagger.yaml"),
    converter.WithTargetVersion("3.0.3"),
)

Learn More

Generated for oastools