Skip to content

v1.8.0

Choose a tag to compare

View all tags
@erraggy erraggy released this 20 Nov 04:29
· 324 commits to main since this release
v1.8.0
1b74870

Summary

This release adds URL loading support for OpenAPI specifications and improves path validation with REST best practice warnings. It also modernizes the codebase to use current Go idioms (Go 1.18+ and 1.22+).

What's New

URL Loading Support

Load OpenAPI specifications directly from HTTP/HTTPS URLs in addition to local files:

# Validate specs from URLs
oastools validate https://example.com/api/openapi.yaml

# Parse from URLs
oastools parse https://petstore3.swagger.io/api/v3/openapi.json

# Convert specs from URLs
oastools convert -t 3.0.3 https://example.com/api/swagger.yaml -o openapi.yaml

Features:

  • HTTP/HTTPS URL support for parse, validate, and convert commands
  • Automatic format detection from URL extension or Content-Type header
  • 30-second timeout for HTTP requests
  • Version-aware User-Agent header (oastools/1.8.0)

Known Limitation: Relative $ref paths in URL-loaded specs resolve against the current directory, not relative to the URL.

Path Validation Improvements

Enhanced path validation with REST best practice warnings:

  • Trailing slashes now generate warnings instead of errors (aligned with OAS spec)
  • Comprehensive path validation catches malformed templates:
    • Consecutive slashes (//)
    • Reserved characters (#, ?)
    • Unclosed/unopened braces
    • Empty parameter names
    • Duplicate parameter names
    • Paths not starting with /

Example:

$ oastools validate api.yaml
...
Warnings (2):
  ⚠ paths./users/: Path has trailing slash, which is discouraged by REST best practices
    Spec: https://spec.openapis.org/oas/v3.0.3.html#paths-object

Code Modernization

Updated codebase to use modern Go idioms:

  • interface{} → any: 233 replacements across 27 files (Go 1.18+)
  • Modern for loops: Updated to use range over int syntax (Go 1.22+)

No functional changes—purely stylistic improvements for better readability.

Changes

Features

  • parser: Add URL loading support with HTTP/HTTPS (#20)

    • New fetchURL() method with timeout and error handling
    • Format detection from URL extension and Content-Type header
    • User-Agent header with version information
    • Comprehensive test suite (46 tests for URL functionality)

  • validator: Improve path validation (#21)

    • Change trailing slashes from errors to warnings
    • Add comprehensive path template validation (17 test cases)
    • Extract checkTrailingSlash() helper for DRY compliance
    • Update package documentation with path validation details

Refactoring

  • codebase: Modernize Go code style (#21)
    • Replace interface{} with any (233 occurrences)
    • Update for loops to use range over int (3 loops)
    • No functional changes

Documentation

  • README: Add URL loading examples and limitations
  • validator: Document path validation and REST best practices
  • planning: Remove completed documentation (code-style, goreleaser)

Technical Details

Compatibility:

  • Go 1.24 required for range over int syntax
  • All 465 tests passing
  • No breaking changes to public APIs

Performance:

  • URL loading adds ~200-500ms latency (network dependent)
  • No impact on local file operations
  • Same performance characteristics as v1.7.2 for parsing/validation

Installation

Homebrew (Recommended)

brew tap erraggy/oastools
brew install oastools

To upgrade from a previous version:

brew upgrade oastools

Binary Download

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

Available for:

  • macOS (Intel and Apple Silicon)
  • Linux (x86_64, ARM64, i386)
  • Windows (x86_64, i386)

Go Install

go install github.com/erraggy/oastools/cmd/oastools@v1.8.0

Related PRs

  • #20 - feat(parser): add URL loading support
  • #21 - feat(validator): improve path validation and modernize Go code style

Full Changelog

v1.7.2...v1.8.0

Assets 10
Loading