Skip to content

Getting Started

This guide walks you through installing api-style-spec and linting your first OpenAPI specification.

Installation

From Source (Go)

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

Verify Installation

api-style version

Your First Lint

Create a simple OpenAPI specification:

# openapi.yaml
openapi: "3.1.0"
info:
  title: My API
  version: "1.0.0"
paths:
  /user:
    get:
      responses:
        "200":
          description: OK

Run the linter:

api-style lint openapi.yaml

You'll see output like:

API Style Lint Report
=====================

Status: FAIL
Errors: 1, Warnings: 2, Info: 0, Hints: 0

Errors:
  - [URI-001] Use plural resource names
    $.paths['/user']

Warnings:
  - [operation-description] operation method `GET` is missing a description
    $.paths['/user'].get

Understanding Violations

Each violation includes:

Field Description
Rule ID Unique identifier (e.g., URI-001)
Message Human-readable explanation
Path JSON path to the violation location
Severity error, warn, info, or hint

Fixing Violations

Update your spec to fix the violations:

# openapi.yaml
openapi: "3.1.0"
info:
  title: My API
  version: "1.0.0"
  description: A sample API
paths:
  /users:  # Changed from /user to /users (plural)
    get:
      summary: List users
      description: Returns a list of all users
      operationId: listUsers
      responses:
        "200":
          description: OK

Run again:

api-style lint openapi.yaml

API Style Lint Report
=====================

Status: PASS
Errors: 0, Warnings: 0, Info: 0, Hints: 0

No violations found.

Using Different Profiles

api-style-spec includes profiles based on industry guidelines:

# Use Azure/Microsoft guidelines
api-style lint openapi.yaml --profile azure

# Use Google API Design Guide
api-style lint openapi.yaml --profile google

# Use Zalando RESTful Guidelines
api-style lint openapi.yaml --profile zalando

See Using Profiles for details on each profile.

Output Formats

Text (default)

api-style lint openapi.yaml

JSON

api-style lint openapi.yaml --format json

SARIF (for IDE integration)

api-style lint openapi.yaml --format sarif --output report.sarif

Combined Analysis

For comprehensive review including LLM-based semantic analysis:

# Requires ANTHROPIC_API_KEY
export ANTHROPIC_API_KEY=sk-ant-...
api-style analyze openapi.yaml --profile azure

This combines:

  1. Deterministic linting (fast, CI-friendly)
  2. LLM evaluation (semantic analysis of design quality)
  3. GO/NO-GO decision for production readiness

Configuration File

Create .api-style.yaml in your project root to configure default options:

# .api-style.yaml
profile: azure
level: silver

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

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

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

CLI flags override config file settings. See the Configuration Reference for all options.

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 openapi.yaml swagger.yaml

Watch Mode

Continuously lint as you edit:

api-style lint openapi.yaml --watch

The watcher:

  • Runs initial lint on startup
  • Re-lints when files change
  • Shows timestamps for each run
  • Exits cleanly with Ctrl+C

Git Pre-Commit Hook

Block commits with API style violations:

api-style hooks init

This installs a pre-commit hook that lints staged OpenAPI files. See Hooks Reference for details.

Next Steps