Skip to content

README.md

Latest commit

 

History

History
181 lines (143 loc) · 6.37 KB

README.md

File metadata and controls

181 lines (143 loc) · 6.37 KB

API Style Spec

Go CI Go Lint Go SAST Go Report Card Docs Docs Visualization License

Machine-readable API style specification format that generates human documentation, linting rules, LLM evaluation rubrics, and AI agent instructions from a single source of truth.

Overview

API style guides from Microsoft, Google, and Zalando have become industry standards, but they exist only as human-readable documents. api-style-spec creates a machine-readable specification format that serves as the canonical source, generating all artifacts from one definition.

api-style-spec (source of truth)
    ├── Human Style Guide (Markdown)
    ├── Deterministic Linters (Spectral/vacuum)
    ├── LLM Review Rubrics
    ├── AI Agent Instructions (Claude Code, Kiro)
    └── MCP Server Tools

Features

  • 📋 Unified Specification - Define rules once, generate all artifacts
  • ✅ Deterministic Linting - Fast, CI-friendly checks via vacuum
  • 🧠 LLM Evaluation - Semantic analysis for rules that can't be linted
  • 🏢 Industry Profiles - Pre-built profiles based on Microsoft, Google, Zalando guidelines
  • 🏆 Conformance Levels - Graduated compliance (bronze/silver/gold)
  • 🌐 Multi-Platform - CLI, Web UI, MCP server, AI agents

Installation

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

Quick Start

# Lint an OpenAPI specification
api-style lint openapi.yaml

# Lint with a specific profile
api-style lint openapi.yaml --profile azure

# Lint multiple files with glob patterns
api-style lint api/*.yaml --recursive

# Watch mode for continuous linting
api-style lint openapi.yaml --watch

# Combined lint + LLM evaluation
api-style analyze openapi.yaml --profile azure --level silver

# Generate human-readable style guide
api-style generate guide --spec my-style.json --output docs/

Configuration

Create .api-style.yaml in your project root:

# .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"

severity-overrides:
  URI-002: warn

See .api-style.yaml.example for a complete example.

Specification Format

{
  "$schema": "https://api-style-spec.dev/schema/v1/api-style-spec.schema.json",
  "version": "1.0.0",
  "name": "my-api-style",
  "extends": ["default"],

  "rules": [
    {
      "id": "URI-001",
      "title": "Use plural resource names",
      "category": "uri-design",
      "severity": "error",
      "rationale": "Plural resources improve consistency.",
      "examples": {
        "good": ["/users", "/orders"],
        "bad": ["/user", "/order"]
      },
      "enforcement": {
        "type": "spectral",
        "function": "pattern",
        "options": {"match": "^/[a-z]+s(/|$)"}
      }
    }
  ]
}

CLI Commands

Command Description
api-style lint Deterministic linting (supports glob patterns, --watch, --recursive)
api-style evaluate LLM-based evaluation
api-style analyze Combined lint + evaluate
api-style generate guide Generate Markdown documentation
api-style generate spectral Generate Spectral ruleset
api-style hooks Generate AI assistant hooks
api-style hooks init Install git pre-commit hook
api-style diff Breaking change detection
api-style serve mcp Start MCP server
api-style serve web Start Web UI

Built-in Profiles

Profile Based On Rules
default Common best practices ~30
azure Microsoft/Azure guidelines ~80
google Google API Design Guide ~60
zalando Zalando RESTful Guidelines ~70

Documentation

Related Projects

License

MIT