Automated API Governance¶
This guide covers setting up a fully automated API design workflow where AI generates OpenAPI specifications, SystemSpec API Style enforces standards, and humans only review—never manually create specs.
Overview¶
Traditional API design requires humans to write OpenAPI specs, which leads to:
- Inconsistent style across teams
- Time-consuming manual reviews
- Style violations discovered late in the process
- Knowledge silos around API best practices
The automated approach flips this:
Requirements → AI Generates Spec → Automated Validation → Human Review → Merge
↑ ↓
└──── Fix & Retry ─────┘
Key principles:
- AI creates, humans review - No manual spec writing
- Validation is blocking - Invalid specs cannot proceed
- Style is codified - Rules defined once, enforced everywhere
- Feedback is immediate - AI fixes issues in real-time
Architecture¶
┌─────────────────────────────────────────────────────────────────┐
│ Developer Workflow │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 1. Requirements 2. AI Generation 3. Validation │
│ ┌───────────┐ ┌───────────────┐ ┌─────────────────┐ │
│ │ "Add user │────▶│ Claude Code │──▶│ systemspec-apistyle │ │
│ │ endpoint" │ │ generates │ │ lints spec │ │
│ └───────────┘ │ openapi.yaml │ └────────┬────────┘ │
│ └───────────────┘ │ │
│ ▲ ▼ │
│ │ ┌──────────────┐ │
│ └──────────────│ Violations? │ │
│ Fix └──────┬───────┘ │
│ │ No │
│ 4. Commit 5. Pre-commit 6. PR Review │
│ ┌───────────┐ ┌───────────────┐ ┌─────────────────┐ │
│ │ git add │────▶│ Hook validates│──▶│ Human approves │ │
│ │ git commit│ │ staged files │ │ design decisions│ │
│ └───────────┘ └───────────────┘ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Setup¶
1. Install Tools¶
# Install systemspec-apistyle CLI
go install github.com/plexusone/systemspec-apistyle/cmd/api-style@latest
# Install MCP server for AI integration
go install github.com/plexusone/systemspec-apistyle/cmd/mcp-api-style@latest
# Verify installation
api-style version
2. Configure Project¶
Create .api-style.yaml in your repository root:
# .api-style.yaml
profile: azure # Or: default, google, zalando
level: silver # Conformance level: bronze, silver, gold
include:
- "api/**/*.yaml"
- "openapi.yaml"
exclude:
- "**/generated/**"
- "**/vendor/**"
# Exceptions require documented justification
exceptions: []
# No severity downgrades by default - enforce all rules
severity-overrides: {}
3. Generate Spectral Ruleset¶
Export rules to Spectral format for editor integration:
This creates a standalone Spectral ruleset that works with:
- VS Code Spectral extension
- JetBrains OpenAPI plugin
- Any Spectral-compatible tool
4. Install Pre-Commit Hook¶
This blocks commits containing API style violations.
5. Configure AI Assistant¶
For Claude Code, add MCP server to .claude/settings.json:
Or generate auto-lint hooks:
Workflow: AI-Generated API Design¶
Step 1: Express Requirements in Natural Language¶
Instead of writing OpenAPI YAML, describe what you need:
Create a REST API endpoint for user registration.
Requirements:
- POST /users endpoint
- Request body: email, password, name (all required)
- Response: user object with id, email, name, createdAt
- Error responses for validation failures and duplicates
- Follow Azure API guidelines
Step 2: AI Generates the Spec¶
Claude Code (or your AI assistant) generates the OpenAPI spec:
# Generated by AI - openapi.yaml
openapi: "3.1.0"
info:
title: User Service API
version: "1.0.0"
paths:
/users:
post:
operationId: createUser
summary: Register a new user
description: Creates a new user account with the provided details.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserRequest'
responses:
"201":
description: User created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/User'
"400":
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
"409":
description: User already exists
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
# ... components defined below
Step 3: Automatic Validation¶
When the AI writes the file, SystemSpec API Style validates it immediately:
If there are violations, the AI sees them instantly:
[15:32:01] File changed: openapi.yaml
openapi.yaml: FAIL (errors: 2, warnings: 1)
- [URI-001] Use plural resource names
- [DOC-001] Operation must have a description
The AI then fixes the issues without human intervention.
Step 4: Commit with Pre-Commit Validation¶
The pre-commit hook runs:
Linting staged OpenAPI specifications...
Checking openapi.yaml... OK
All OpenAPI specifications passed linting
[main abc1234] feat(api): add user registration endpoint
If violations exist, the commit is blocked:
Linting staged OpenAPI specifications...
Checking openapi.yaml... FAILED
- [URI-001] Use plural resource names
$.paths['/user']
Pre-commit hook failed: API style violations found
Fix the issues above or use 'git commit --no-verify' to skip
Step 5: Human Review (Design Decisions Only)¶
The PR contains:
- AI-generated OpenAPI spec (validated)
- No style violations (enforced by automation)
Human reviewers focus on:
- Does the API meet business requirements?
- Are the resource names semantically correct?
- Is the data model appropriate?
- Are there security considerations?
They do NOT review:
- Plural vs singular naming (automated)
- HTTP method correctness (automated)
- Response code consistency (automated)
- Documentation completeness (automated)
Advanced: Continuous Governance¶
Watch Mode for Development¶
Run continuous validation during development:
Output:
Starting watch mode...
Watching 5 file(s). Press Ctrl+C to stop.
api/users.yaml: PASS (errors: 0, warnings: 0)
api/orders.yaml: PASS (errors: 0, warnings: 1)
api/products.yaml: PASS (errors: 0, warnings: 0)
Watching for changes...
[15:45:12] File changed: api/users.yaml
api/users.yaml: PASS (errors: 0, warnings: 0)
CI/CD Pipeline Integration¶
Add to your GitHub Actions workflow:
# .github/workflows/api-lint.yaml
name: API Style Check
on:
pull_request:
paths:
- 'api/**/*.yaml'
- 'openapi.yaml'
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install api-style
run: go install github.com/plexusone/systemspec-apistyle/cmd/api-style@latest
- name: Lint OpenAPI specs
run: api-style lint api/ --recursive --format sarif --output results.sarif
- name: Upload SARIF results
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: results.sarif
Multi-File Project Structure¶
For larger projects:
api/
├── .api-style.yaml # Project config
├── users/
│ └── openapi.yaml # User service API
├── orders/
│ └── openapi.yaml # Order service API
├── products/
│ └── openapi.yaml # Product service API
└── shared/
└── components.yaml # Shared schemas
Lint all at once:
Conformance Level Progression¶
Start with bronze, progress to gold:
As the API matures:
For public APIs:
AI Prompting Best Practices¶
Effective Prompts for API Generation¶
Good prompt:
Create an OpenAPI 3.1 spec for a product catalog API.
Endpoints needed:
- GET /products - list with pagination (cursor-based)
- GET /products/{id} - get single product
- POST /products - create product (admin only)
- PATCH /products/{id} - update product (admin only)
- DELETE /products/{id} - delete product (admin only)
Product fields: id, name, description, price, category, createdAt, updatedAt
Follow Azure API guidelines. Use RFC 7807 for errors.
Include proper security schemes (OAuth2 + API key).
Why it works:
- Specifies OpenAPI version
- Lists all endpoints with methods
- Defines the data model
- References the style guide
- Mentions error format
- Includes security requirements
Let AI Fix Violations¶
When violations occur, tell the AI:
The linter found these issues:
- [URI-001] Use plural resource names at $.paths['/product']
- [DOC-002] Missing operation description at $.paths['/products'].get
Fix these violations in the OpenAPI spec.
The AI will correct the issues and the lint will re-run automatically.
Troubleshooting¶
Pre-commit Hook Not Running¶
-
Verify hook exists:
-
Check it's executable:
-
Verify api-style is in PATH:
AI Not Seeing Lint Results¶
-
Check MCP server is configured:
-
Or verify auto-lint hooks exist:
Spectral Extension Not Using Rules¶
-
Regenerate the ruleset:
-
Restart your editor
-
Check
.spectral.yamlis in the project root
Summary¶
| Component | Purpose | Command |
|---|---|---|
.api-style.yaml |
Project governance config | (manual creation) |
| Pre-commit hook | Block invalid commits | api-style hooks init |
| Auto-lint hooks | Real-time AI feedback | api-style hooks --format claude |
| Watch mode | Continuous validation | api-style lint --watch |
| Spectral ruleset | Editor integration | api-style generate spectral |
| CI/CD integration | PR validation | api-style lint --format sarif |
The result: 100% automated style enforcement with humans reviewing only design decisions, not style compliance.
Next Steps¶
- Configuration Reference - All config options
- CLI Reference - Complete command documentation
- Custom Rules - Define organization-specific rules
- MCP Server - AI assistant integration details