Skip to content

Getting Started

This guide walks you through installing systemspec-apistyle and linting your first OpenAPI specification.

Installation

From Source (Go)

go install github.com/plexusone/systemspec-apistyle/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

SystemSpec API Style 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.

Starting from Exemplars

Use exemplar specifications as templates for new APIs:

# List available exemplars
api-style exemplar list

# View an exemplar
api-style exemplar show default-minimal

# Copy as starting point
api-style exemplar copy default-minimal ./my-api.yaml

Exemplars demonstrate best practices for each style profile.

Using Design Patterns

Explore reusable solutions for common API design problems:

# List patterns for a profile
api-style pattern list --profile default

# View pattern details with examples
api-style pattern show cursor-pagination

Patterns include problem descriptions, solutions, code examples, and related rules.

Getting Fix Suggestions

Get AI-powered suggestions to fix violations:

# Include suggestions in lint output
api-style lint openapi.yaml --suggest-fixes

# Or generate suggestions from violations
api-style lint openapi.yaml --format json --output violations.json
api-style suggest-fixes violations.json

Suggestions include the recommended fix, reasoning, and JSON Patch operations for automated fixing.

Next Steps