v1.17.1

What's Changed

Dependencies

• Migrate YAML library: Switched from gopkg.in/yaml.v3 to go.yaml.in/yaml/v4 (#90)

Code Quality

• Expert review improvements (#92):
  • Added new linters to golangci-lint config: goconst, gosec, prealloc, nilerr, errorlint, revive
  • Created internal/schemautil package for type-safe OAS schema handling
  • Created internal/cliutil package with Writef helper for CLI output
  • Refactored benchmarks to use b.Run() sub-benchmarks for better organization
  • All benchmarks now report allocations with b.ReportAllocs()
  • Added godoc cross-package links using Go 1.19+ syntax

Documentation

• Added GEMINI.md for Gemini AI agent instructions (#91)
• Updated benchmark counts in README.md and benchmarks.md (#93)

Changelog

• b87a984 docs: update benchmark counts to reflect current suite (#93)
• c14d1d5 refactor: implement expert review feedback improvements (#92)
• d4f7da5 docs: add GEMINI.md with Gemini agent instructions (#91)
• 879612f chore(deps): migrate from gopkg.in/yaml.v3 to go.yaml.in/yaml/v4 (#90)

Full Changelog: v1.17.0...v1.17.1

v1.17.0

Overview

v1.17.0 enables CLI pipelining and enhances code generation with template-based architecture. This release focuses on making oastools a first-class Unix pipeline citizen while improving maintainability of the code generator.

Major Features

🔗 CLI Pipelining Support (#88)

All CLI commands now work seamlessly in Unix pipelines, enabling powerful composition with tools like jq, yq, and other OpenAPI processing utilities.

New Capabilities:

1. Stdin Input - Read from stdin using - as the file path
2. Quiet Mode - Suppress diagnostic output with --quiet or -q
3. Structured Output - JSON/YAML output formats for programmatic processing

Commands Updated:

• ✅ parse - Full stdin and quiet mode support
• ✅ validate - Stdin, quiet mode, and structured output (JSON/YAML)
• ✅ convert - Full stdin and quiet mode support
• ✅ diff - Structured output support (JSON/YAML)

Pipeline Examples

Convert and Validate in One Pipeline

# Convert OAS 2.0 to 3.0.3 and immediately validate
cat swagger.yaml | oastools convert -q -t 3.0.3 - | oastools validate -q -

# Chain multiple operations
cat swagger.yaml | \
  oastools convert -q -t 3.0.3 - | \
  oastools validate -q --format json - | \
  jq '.Valid'

Extract Information with jq

# Get the API title
oastools parse -q openapi.yaml | jq -r '.info.title'

# List all operation IDs
oastools parse -q openapi.yaml | \
  jq -r '.paths[].*.operationId' | \
  sort | uniq

# Count total number of endpoints
oastools parse -q openapi.yaml | \
  jq '[.paths | to_entries[] | .value | keys[]] | length'

# Extract all security schemes
oastools parse -q openapi.yaml | \
  jq '.components.securitySchemes | keys[]'

Validation in CI/CD Pipelines

# Validate with JSON output for automated testing
oastools validate --format json openapi.yaml | \
  jq -e '.Valid' > /dev/null || exit 1

# Check validation and get error count
ERRORS=$(oastools validate --format json openapi.yaml | jq '.Errors | length')
if [ "$ERRORS" -gt 0 ]; then
  echo "Validation failed with $ERRORS errors"
  exit 1
fi

# Validate multiple files and collect results
for file in specs/*.yaml; do
  echo "Validating $file..."
  oastools validate -q --format json "$file" | \
    jq -r '"\(.SourcePath): \(if .Valid then "✓ Valid" else "✗ Invalid" end)"'
done

Detect Breaking Changes

# Check for breaking changes between API versions
oastools diff --format json --breaking api-v1.yaml api-v2.yaml | \
  jq -e '.HasBreakingChanges == false' || {
    echo "Breaking changes detected!"
    exit 1
  }

# Get details of breaking changes
oastools diff --format json --breaking api-v1.yaml api-v2.yaml | \
  jq -r '.Changes[] | select(.Severity == "Critical" or .Severity == "Error") | 
    "[\(.Severity)] \(.Path): \(.Message)"'

# Count changes by severity
oastools diff --format json api-v1.yaml api-v2.yaml | \
  jq '.Changes | group_by(.Severity) | 
    map({severity: .[0].Severity, count: length})'

Multi-Stage Conversion Pipelines

# Convert OAS 2.0 → 3.0.3, validate, then generate client
cat swagger-v2.yaml | \
  oastools convert -q -t 3.0.3 - | \
  tee oas3.yaml | \
  oastools validate -q - && \
  oastools generate --mode client --output ./client oas3.yaml

# Process multiple specs through conversion pipeline
for file in legacy/*.yaml; do
  base=$(basename "$file" .yaml)
  cat "$file" | \
    oastools convert -q -t 3.1.0 - | \
    oastools validate -q --format json - | \
    jq --arg name "$base" '{name: $name, valid: .Valid, errors: (.Errors | length)}' 
done | jq -s '.'

Advanced Composition

# Merge multiple specs (using external tool), validate, convert
yq eval-all 'select(fileIndex == 0) * select(fileIndex == 1)' base.yaml overlay.yaml | \
  oastools validate -q - | \
  oastools convert -q -t 3.1.0 -

# Extract and transform with jq, then validate the result
oastools parse -q openapi.yaml | \
  jq '.paths |= with_entries(select(.key | startswith("/api/v2")))' | \
  oastools validate -q --format json -

# Diff two versions and format output
oastools diff --format json v1.yaml v2.yaml | \
  jq -r '.Changes[] | "[\(.Severity | ascii_upcase)] \(.Message)"' | \
  grep -E "(CRITICAL|ERROR)"

Format Conversion

# Convert YAML to JSON
oastools parse -q openapi.yaml > openapi.json

# Convert JSON to YAML (parser preserves input format)
oastools parse -q openapi.json | yq -P > openapi.yaml

Quiet Mode Details

When --quiet (or -q) is enabled:

• ✅ Suppresses "Parsing...", "Validating...", "Converting..." messages
• ✅ Suppresses progress indicators and status updates
• ✅ Only outputs the document or structured result
• ✅ Errors still go to stderr for proper error handling
• ✅ Exit codes remain unchanged (0 = success, non-zero = failure)

Structured Output Formats

JSON Output (--format json)

{
  "SourcePath": "openapi.yaml",
  "Valid": true,
  "Errors": [],
  "Warnings": [],
  "OASVersion": "3.0.3"
}

YAML Output (--format yaml)

sourcePath: openapi.yaml
valid: true
errors: []
warnings: []
oasVersion: 3.0.3

Diff JSON Output

{
  "HasBreakingChanges": true,
  "Changes": [
    {
      "Path": "paths./users.get.parameters[0]",
      "Message": "Required parameter 'userId' removed",
      "Severity": "Critical"
    }
  ]
}

🏗️ Template-Based Code Generation (#89)

Refactored the generator package from string concatenation to Go's text/template system, improving maintainability and code quality.

Key Improvements:

• ✅ Clear separation between data building (Go) and formatting (templates)
• ✅ Strongly-typed data structures instead of string manipulation
• ✅ Template-based type generation for better maintainability
• ✅ Test coverage improved from 76.2% to 84.2% (+8%)
• ✅ All 2,075 tests pass with byte-for-byte identical output

Technical Details:

• Created template_builders.go (455 lines) with builder functions
• Added templates/types.go.tmpl as main orchestrator
• Removed 268 lines of obsolete string-building code
• Net -84 lines overall while improving structure

Impact:
This is an internal refactoring with no API changes or breaking changes. The code generator continues to work exactly as before but with better maintainability for future enhancements.

Other Changes

• Enhanced error messages across pipeline commands
• Improved test coverage for CLI command flags (51.7%, up from 11.6%)
• Code quality improvements and refactoring

Compatibility

• Go Version: 1.24+
• OAS Support: 2.0, 3.0.x, 3.1.x, 3.2.0
• Backward Compatible: All existing APIs remain unchanged

Installation

# Install latest version
go install github.com/erraggy/oastools/cmd/oastools@v1.17.0

# Or download pre-built binaries from the release page

Upgrade Notes

No breaking changes. All existing scripts and integrations will continue to work. New pipeline features are opt-in via new flags (-q, --format, - for stdin).

Performance

Performance characteristics remain consistent with v1.16.0:

Operation	Small (5 paths)	Medium (40 paths)	Large (500 paths)
Parse	142 μs	1,130 μs	14,131 μs
Validate	143 μs	1,160 μs	14,635 μs
Convert (OAS2→3)	153 μs	1,314 μs	-
Join (2 docs)	115 μs	-	-

Benchmarks measured on Apple M4, Go 1.24

What's Next

Pipeline support opens up many possibilities for advanced workflows:

• Integration with API governance tools
• Automated API documentation pipelines
• CI/CD validation and breaking change detection
• Custom OpenAPI transformations and analysis

We welcome feedback and examples of how you're using oastools in pipelines!

v1.16.2

Summary

Patch release with improved HTTP client generation and documentation updates.

What's New

• Add default User-Agent header to generated HTTP clients (#83) - Generated HTTP clients now include a default User-Agent header for better API compatibility and request tracking

Improvements

• Add AGENTS.md for GitHub Copilot coding agent support (#85) - Better IDE integration documentation
• Update README description to match repository metadata (#86)

Related PRs

• #83 - Add default User-Agent header to generated HTTP clients
• #85 - Add AGENTS.md for GitHub Copilot coding agent support
• #86 - chore(readme): updates description to match repo description

v1.16.1

Documentation Update

This patch release updates comprehensive documentation for the generator package that was released in v1.16.0.

What's New in Documentation

• README.md: Added generator package to features list with CLI and library API examples
• doc.go: Updated module-level documentation to enumerate generator as the seventh public package
• docs/developer-guide.md:
  • Added Generate Command section with CLI usage, flags, and examples
  • Added Generator Package section with code generation patterns
  • Added Builder Package section with programmatic construction patterns
• docs/cli-reference.md: Added complete generate command reference with type mapping and exit codes
• benchmarks.md: Updated package count references

Why This Release

This documentation update ensures that:

• pkg.go.dev displays the updated README and module documentation
• Developers can discover the generator package capabilities
• Comprehensive examples are available for both CLI and library usage

Install

# Homebrew
brew upgrade oastools

# Go
go get github.com/erraggy/oastools@v1.16.1

# Binary download
# See assets below for your platform

Related Issues

• Documentation for generator feature released in PR #80

v1.16.0

Overview

v1.16.0 introduces the new Generator package and CLI command for generating idiomatic Go code from OpenAPI specifications. This release focuses on code generation capabilities for both client and server implementations, with extensive benchmarking improvements.

Major Features

🆕 Generator Package & CLI Command

The new generator package provides a comprehensive solution for generating Go code from OpenAPI Specification documents. This release includes:

Library (github.com/erraggy/oastools/generator):

• Generate Go types from OAS schemas with proper support for optional/nullable fields
• Create client SDKs with type-safe HTTP methods
• Generate server interfaces for framework-agnostic implementation
• Full support for OAS 3.x specifications (OAS 3.0, 3.1, 3.2)
• OAS 2.0 support with automatic conversion to OAS 3.0 semantics

CLI Command (oastools generate):

• --mode client - Generate HTTP client with all operations
• --mode server - Generate server interfaces and types
• --output - Specify output directory for generated code
• Automatic package name inference from API title or custom naming
• Support for both YAML and JSON OAS files
• Comprehensive error reporting with actionable feedback

Key Capabilities:

• Automatic Go type generation from JSON Schema and OAS schemas
• Proper handling of nullable types, enums, and constraints
• Request/response type generation with validation annotations
• Client methods with idiomatic Go signatures
• Server handler interfaces for HTTP frameworks
• Comments and documentation from OAS descriptions

API Design:

• Functional options API: generator.GenerateWithOptions(...)
• Struct-based API: generator.New(), Generator.Generate()
• Result tracking with GeneratorResult including issues and statistics

📊 Benchmark Updates

This release includes comprehensive benchmark updates reflecting the current performance characteristics of the oastools suite. Benchmark data has been refreshed to provide accurate performance baseline information for future comparisons.

Other Changes

• Improved error messages and validation feedback across all packages
• Enhanced test coverage for existing functionality
• Code quality improvements and refactoring

Compatibility

• Go Version: 1.24+
• OAS Support: 2.0, 3.0.x, 3.1.x, 3.2.0
• Backward Compatible: All existing APIs remain unchanged

Installation

# Build from source
go install github.com/erraggy/oastools/cmd/oastools@v1.16.0

# Try the new generate command
oastools generate --help

v1.15.2

Summary

Version 1.15.2 introduces QUERY HTTP method support for OAS 3.2+, improves test coverage across converter and parser packages, and includes several CI/testing improvements for better stability.

What's New

QUERY HTTP Method Support (OAS 3.2+)

• Add comprehensive support for the QUERY HTTP method introduced in OpenAPI Specification 3.2.0
• New unified GetOperations(pathItem, version) API that automatically returns appropriate methods based on OAS version
• QUERY method support in builder package with version validation
• Proper handling in converter with critical issue detection when converting to OAS 2.0
• Validator now properly validates QUERY operations in OAS 3.2+ documents

Improvements

Test Coverage & Quality

• Improved unit test coverage for converter and parser packages
• Parser paths_json.go coverage increased from 51% to 89.9%
• Converter oas3_to_oas2.go coverage increased from 47.4% to 82.7%
• Converter oas2_to_oas3.go coverage increased from 68.3% to 92%+
• Added comprehensive tests for Link, MediaType, Example, and Encoding

CI/Testing Stability

• Fixed CI workflow resource exhaustion by adding testing.Short() checks
• Fixed race test workflow resource exhaustion by splitting tests
• Improved test execution in resource-constrained environments
• Tests now skip resource-intensive operations in short mode

Code Quality

• Removed unnecessary getOperationsForVersion indirection in validator
• Use >= for OAS 3.2+ version checks to support future versions
• Better forward compatibility for upcoming OAS versions

Documentation

• Cleaned up planning directory and enforced feature branch workflow
• Added comprehensive workflow documentation (WORKFLOW.md)
• Updated workflow to mandate feature branch creation before changes

Related PRs

• #77 - Remove unnecessary getOperationsForVersion indirection in validator
• #76 - fix: use >= for OAS 3.2+ version check to support future versions
• #75 - feat(parser): add QUERY HTTP method support for OAS 3.2+
• #74 - Fix CI workflow resource exhaustion by adding testing.Short() checks
• #73 - Fix race test workflow resource exhaustion by splitting tests and skipping memory-intensive operations
• #72 - Improve unit test coverage for converter and parser packages
• #71 - docs: clean up planning directory and enforce feature branch workflow
• #70 - docs: add comprehensive workflow documentation

Installation

Homebrew

brew update
brew upgrade oastools

v1.15.1

Summary

Version 1.15.1 fixes a critical bug in OAS 2.0 document generation that was introduced in v1.15.0. This patch release ensures that the builder package generates valid OAS 2.0 documents that comply with the OpenAPI Specification 2.0 standard.

Bug Fixes

Critical: OAS 2.0 Generation Fixed

The builder was incorrectly generating OAS 3.x structure (requestBody and response content) for OAS 2.0 documents. This caused validation failures and rendering issues in tools like Swagger UI.

What was fixed:

• Request bodies now generate parameters array with in: "body" instead of requestBody object (OAS 2.0 spec compliant)
• Response bodies now generate direct schema field instead of content map (OAS 2.0 spec compliant)
• Schema is correctly extracted from the first content type
• Description and required flags are properly preserved

Affected methods:

• WithRequestBody - Now generates correct OAS 2.0 body parameters
• WithRequestBodyRawSchema - Now generates correct OAS 2.0 body parameters
• WithResponse - Now generates correct OAS 2.0 response schemas
• WithResponseRawSchema - Now generates correct OAS 2.0 response schemas

Impact:
✅ OAS 2.0 documents now validate correctly against the specification
✅ Swagger UI and other tools can properly render OAS 2.0 documents
✅ Both legacy and raw schema APIs work correctly for OAS 2.0
✅ All existing OAS 3.x functionality remains unchanged
✅ Backward compatible - no breaking changes to public API

Testing

• 6 new unit tests for OAS 2.0 specific behavior
• 2 integration tests for complete OAS 2.0 document generation
• All existing tests continue to pass
• Zero security vulnerabilities

Related PRs

• #69 - Fix OAS 2.0 generation: convert requestBody/content to body parameters/schema

Installation

Homebrew

brew update
brew upgrade oastools

Go Module

go get github.com/erraggy/oastools@v1.15.1

Binary Download

Download the appropriate binary for your platform from the assets below.

Migration Notes

If you're using v1.15.0 with OAS 2.0 documents, upgrade to v1.15.1 immediately. No code changes are required - the fix is automatic.

OAS 3.x documents are not affected by this bug.

v1.15.0

Summary

Version 1.15.0 enhances the builder package with raw schema support and file upload capabilities, making it easier to build complex OpenAPI specifications programmatically. This release adds three new methods that enable advanced use cases like binary file uploads, pre-built schema reuse, and multipart form data handling.

What's New

Raw Schema Support

• WithRequestBodyRawSchema(contentType, schema, opts...) - Attach pre-built schemas directly to request bodies, enabling schema reuse and complex schema definitions
• WithResponseRawSchema(statusCode, contentType, schema, opts...) - Attach pre-built schemas to responses with full control over content types and status codes

File Upload Parameters

• WithFileParam(name, opts...) - First-class support for file upload parameters in both OAS 2.0 and 3.x
• Automatic content type detection (multipart/form-data for files, application/x-www-form-urlencoded for forms)
• Binary file support with proper format specifications
• Complex multipart uploads with metadata
• Parameter constraints properly ignored for file parameters (per OAS spec)

Key Benefits

• Full OAS 2.0 and 3.x compatibility
• Seamless integration with existing builder methods
• All parameter options work with file uploads
• Comprehensive test coverage (14 new unit tests, 4 integration tests)
• Production-ready with godoc examples

Related PRs

• #67 - Add raw schema support and file upload parameters to builder

Installation

Homebrew

brew update
brew upgrade oastools
# or if not installed yet:
brew tap erraggy/oastools
brew install oastools

Go Module

go get github.com/erraggy/oastools@v1.15.0

Binary Download

Download the appropriate binary for your platform from the assets below.

Example Usage

// File upload endpoint (OAS 3.x)
builder := builder.New().SetVersion("3.0.3")
builder.AddOperation("/upload", httputil.MethodPost,
    builder.WithOperationID("uploadFile"),
    builder.WithFileParam("file", builder.WithParamDescription("File to upload")),
)

// Binary response with raw schema
schema := &parser.Schema{
    Type:   "string",
    Format: "binary",
}
builder.AddOperation("/download", httputil.MethodGet,
    builder.WithResponseRawSchema("200", "application/octet-stream", schema),
)

See the builder package documentation for more examples.

v1.14.0

Summary

This release introduces the WithFormParam method to the builder package, making it easy to work with form parameters in both OAS 2.0 and OAS 3.x specifications.

What's New

New WithFormParam Method

The builder package now includes a WithFormParam method that automatically handles the different representations of form parameters across OpenAPI specification versions:

• OAS 2.0: Creates parameters with in: "formData"
• OAS 3.x: Adds form parameters to the request body with application/x-www-form-urlencoded content type

Features

• Works seamlessly with both OAS 2.0 and OAS 3.x
• Supports all standard parameter options (description, required, default values, constraints)
• Can add multiple form parameters to the same operation
• Works with webhooks in OAS 3.1+
• Properly handles form parameters mixed with other parameter types
• Intelligently manages existing request bodies

Usage Example

builder := builder.New("3.0.3")
builder.Operation(httputil.MethodPost, "/users").
    WithFormParam("username", builder.ParamString()).
    WithFormParam("email", builder.ParamString().Required()).
    WithFormParam("age", builder.ParamInteger().WithDefault(18))

For more details, see PR #62.

Additional Changes

• Documentation: Renamed .github/README.md to .github/CONFIGURATION.md to fix repository display priority (#65)
• Configuration: Updated Copilot instructions following best practices (#64)

Related PRs

• #62 - Add WithFormParam method for OAS 2.0 and 3.x form parameters
• #65 - Rename .github/README.md to .github/CONFIGURATION.md to fix repository display priority
• #64 - Configure Copilot instructions following best practices

Installation

Homebrew

brew tap erraggy/oastools
brew install oastools

Go Module

go get github.com/erraggy/oastools@v1.14.0

Binary Download

Download the appropriate binary for your platform from the assets below.

v1.13.1

Summary

This patch release adds comprehensive parameter constraint support to the builder package, enabling developers to define validation rules (min/max values, length constraints, patterns, enums, etc.) when building OpenAPI specifications.

What's New

Parameter Constraint Support

Added 13 new WithParam* option functions to the builder package for defining parameter constraints:

Numeric Constraints:

• WithParamMinimum(min float64) - Sets minimum value
• WithParamMaximum(max float64) - Sets maximum value
• WithParamExclusiveMinimum(exclusive bool) - Whether minimum is exclusive
• WithParamExclusiveMaximum(exclusive bool) - Whether maximum is exclusive
• WithParamMultipleOf(value float64) - Value must be a multiple of this

String Constraints:

• WithParamMinLength(min int) - Minimum string length
• WithParamMaxLength(max int) - Maximum string length
• WithParamPattern(pattern string) - Regex pattern

Array Constraints:

• WithParamMinItems(min int) - Minimum array items
• WithParamMaxItems(max int) - Maximum array items
• WithParamUniqueItems(unique bool) - Whether items must be unique

Value Constraints:

• WithParamEnum(values ...any) - Allowed enumeration values
• WithParamDefault(value any) - Default value

Build-Time Constraint Validation

The builder now validates constraints at build time and reports errors for:

• Invalid ranges (e.g., minimum > maximum)
• Negative length/item constraints
• Invalid regex patterns
• Non-positive multipleOf values

OAS Version Support

Constraints work correctly across all OAS versions:

• OAS 3.x: Applied to parameter's Schema field
• OAS 2.0: Applied directly to Parameter struct fields

Example Usage

spec := builder.New(parser.OASVersion320).
    SetTitle("Pet Store API").
    SetVersion("1.0.0")

spec.AddOperation(http.MethodGet, "/pets",
    builder.WithOperationID("listPets"),
    builder.WithQueryParam("limit", int32(0),
        builder.WithParamDescription("Maximum number of pets to return"),
        builder.WithParamMinimum(1),
        builder.WithParamMaximum(100),
        builder.WithParamDefault(20),
    ),
    builder.WithQueryParam("status", string(""),
        builder.WithParamEnum("available", "pending", "sold"),
    ),
    builder.WithQueryParam("name", string(""),
        builder.WithParamMinLength(1),
        builder.WithParamMaxLength(50),
        builder.WithParamPattern("^[a-zA-Z]+$"),
    ),
)

Performance

The implementation includes performance improvements through internal refactoring:

• Builder operations are 0.3-4.4% faster
• Memory usage reduced by 1.7-5.4%
• 1-3 fewer allocations per operation

Related PR

• #60 - Add parameter constraint support to builder package

Installation

Homebrew

brew tap erraggy/oastools
brew upgrade oastools  # or install if first time

Go Module

go get github.com/erraggy/oastools@v1.13.1

Binary Download

Download the appropriate binary for your platform from the assets below.