Skip to content

v0.2.0

Released: 2026-06-07

This release adds project-level configuration, multi-file linting, watch mode, and git pre-commit hooks—enabling fully automated API governance workflows.

Highlights

  • Configuration file support (.api-style.yaml) for project-level governance settings
  • Multi-file linting with glob patterns and recursive directory search
  • Watch mode for continuous linting during development
  • Git pre-commit hook generator for blocking commits with violations

Installation

go install github.com/plexusone/api-style-spec/cmd/api-style@v0.2.0

Upgrade from v0.1.0

No breaking changes. All v0.1.0 commands continue to work.

New optional features:

  1. Add .api-style.yaml to your project root for default settings
  2. Use --recursive to lint directories
  3. Use --watch for continuous linting
  4. Run api-style hooks init to install pre-commit hooks

Features

Configuration File Support

Define project-level settings in .api-style.yaml:

profile: azure
level: silver

include:
  - "api/**/*.yaml"

exclude:
  - "**/generated/**"

exceptions:
  - rule: URI-001
    paths: ["/legacy/**"]
    reason: "Legacy API cannot be changed"

severity-overrides:
  URI-002: warn
  • Auto-discovery of config files (.api-style.yaml, .api-style.yml, api-style.yaml)
  • CLI flags override config file settings
  • Use --config for explicit config file path

Multi-File Linting

Lint multiple files at once:

# Glob patterns
api-style lint api/*.yaml

# Recursive directory search
api-style lint . --recursive

# Multiple arguments
api-style lint users.yaml orders.yaml products.yaml
  • Include/exclude pattern filtering
  • ** double-star glob support for recursive matching
  • Aggregated MultiLintReport with per-file results

Watch Mode

Continuous linting during development:

api-style lint openapi.yaml --watch
  • Re-lints on file changes
  • Debouncing to coalesce rapid changes
  • Graceful shutdown with Ctrl+C
  • Timestamps for each run

Git Pre-Commit Hook

Block commits with API style violations:

api-style hooks init
api-style hooks init --profile azure --level silver
api-style hooks init --force  # Overwrite existing hook
  • Lints staged OpenAPI/Swagger files
  • Blocks commits on errors
  • Bypass with git commit --no-verify

New CLI Flags

lint command

Flag Short Description
--config -c Explicit config file path
--recursive -r Search directories recursively
--watch -w Watch files and re-lint on changes

hooks init command

Flag Short Description
--profile -p Style profile for linting
--level -l Conformance level to enforce
--force Overwrite existing hook

Documentation

New documentation added:

  • Configuration File Reference - Complete .api-style.yaml options
  • Automated API Governance Guide - AI-first API design workflow
  • Pre-Commit Hook Reference - Git hook setup and usage

Updated documentation:

  • CLI Reference with new flags and commands
  • Getting Started guide with config, multi-file, watch sections
  • Examples README with new usage patterns

Dependencies

  • Added github.com/fsnotify/fsnotify v1.10.1 for file watching