v0.1.0¶

Released: 2026-06-06

Initial release of API Style Spec, a 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.

Highlights¶

OpenAPI style linting with vacuum integration and configurable style profiles (Azure, Google, custom)
LLM-powered API evaluation using Claude for semantic analysis beyond static rules
MCP server for Claude Desktop and Claude Code integration with resources and prompts
Web UI with Lit components and REST API backend for browser-based linting

Installation¶

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

Features¶

Core Types & Schema¶

Core types package with LintReport, Violation, StyleProfile, and EvaluationResult structs
JSON Schema generation from Go types with embedded schemas

Linting Engine¶

Vacuum-based linting engine with severity mapping and JSON path extraction
Style profile loading from YAML/JSON with built-in Azure and Google profiles
Profile inheritance via extends field for building on base profiles

LLM Evaluation¶

LLM evaluation with Claude using structured prompts and JSON output
Evaluation categories: naming, structure, documentation, security, versioning
Analysis orchestrator combining static linting and LLM evaluation

Generators¶

Spectral ruleset generator from style profiles
Markdown report generator with configurable output options

CLI¶

CLI with lint, analyze, and evaluate commands
Multiple output formats: text, JSON, SARIF
Exit codes based on violation severity for CI integration

MCP Server¶

MCP server with openapi:// resource URIs for spec access
MCP prompts for guided API review workflows
MCP tools for linting and evaluation from Claude Desktop

Claude Code Integration¶

Claude Code hooks for pre-commit and post-save linting
Claude Code skills for /lint and /evaluate slash commands

IDE Integration¶

SARIF 2.1.0 output format for IDE integration (VS Code, JetBrains)
GitHub Code Scanning compatible SARIF output

Web UI¶

REST API server with /api/lint and /api/profiles endpoints
CORS support for development and cross-origin requests
Web UI with Lit components: spec editor, profile selector, results panel
Vite-based frontend build with hot module replacement

Examples¶

Example OpenAPI specs: PetStore and E-Commerce APIs
Example custom style profiles demonstrating profile customization

Documentation¶

MkDocs documentation site with Material theme
Getting started guide with installation and basic usage
Profile customization guide with YAML examples
MCP integration guide for Claude Desktop setup
Feature roadmap with prioritized enhancements

Test Coverage¶

Package	Coverage
analyze	82%
judge	76%
lint	79%
sarif	92%