lint

API Lint

Check OpenAPI spec and codebase for consistency. Finds inconsistencies in manually written specs/code.

MCP Dependency Check

Before executing this command, invoke skill: mcp-dependency

• Verify OpenAPI Sync MCP server is installed
• If not available, offer to install via npm install -g @jhlee0409/openapi-sync-mcp
• Only proceed after MCP is confirmed available

Target Selection

/oas:lint           → Check both spec + code (default)
/oas:lint --spec    → Check OpenAPI spec only
/oas:lint --code    → Check codebase only

Usage

# Full check (smart caching for spec)
/oas:lint

# Specific rule only
/oas:lint --rule=naming
/oas:lint --rule=response-structure

# Fix suggestions
/oas:lint --fix

# Force fetch spec (bypass cache)
/oas:lint --force

# Use cached spec only (offline)
/oas:lint --offline

Smart Caching

Use skill: cache-manager

When linting spec (--spec or default):
  1. Check if spec changed (HEAD request / mtime)
  2. If unchanged → Use cached spec
  3. If changed → Fetch new spec, update cache

When linting code only (--code):
  → No spec fetch needed

Part 1: Spec Lint Rules (--spec)

1. response-key-consistency

Check list response key naming consistency:

⚠️ INCONSISTENT: List response keys vary

  Found 4 different patterns:
    "items"    → 12 endpoints (48%)
    "results"  → 8 endpoints (32%)
    "videos"   → 3 endpoints (12%)
    "projects" → 2 endpoints (8%)

  Examples:
    GET /shortform/videos     → { videos: [...] }
    GET /project/projects     → { results: [...] }
    GET /workspace/users      → { items: [...] }

  💡 Recommendation:
    Standardize on "items" (most common)
    Or use resource-specific names consistently

2. timestamp-naming

Timestamp field naming consistency:

⚠️ INCONSISTENT: Timestamp field naming varies

  Found 3 patterns:
    "created_at"   → 15 schemas
    "created"      → 8 schemas
    "createdAt"    → 3 schemas (camelCase)

  Examples:
    UserProfile.created_at
    Project.created
    VideoClip.createdAt

  💡 Recommendation:
    Standardize on "created_at" (most common, follows snake_case)