Oas

openapi-sync (oas)

English | 한국어

A Claude Code plugin that syncs OpenAPI specs with your codebase.

What makes it different: Instead of hardcoded templates, it learns from your existing code and generates new API code in the same style.

"Show me one API file, I'll generate 100 more like it"

Installation

1. Install MCP Server (Required)

The OAS plugin requires the OpenAPI Sync MCP server:

npm install -g @jhlee0409/openapi-sync-mcp

Then add to your Claude config (~/.claude.json or project .mcp.json):

{
  "mcpServers": {
    "oas": {
      "command": "openapi-sync-mcp",
      "args": []
    }
  }
}

2. Install Plugin

# Add plugin marketplace (run once)
/plugin marketplace add jhlee0409/claude-plugins

# Install plugin
/plugin install oas@jhlee0409-plugins

For development/testing:

# Load plugin from local directory
claude --plugin-dir /path/to/claude-plugins

Note: If MCP server is not installed, the plugin will prompt you to install it automatically when running any /oas:* command.

Quick Start

# 1. Initialize with your OpenAPI spec (URL or local path)
/oas:init https://api.example.com/openapi.json
# or
/oas:init ./docs/openapi.yaml

# 2. Generate code from spec
/oas:sync

# 3. Check consistency
/oas:lint

Commands

Command	Description
/oas:init <url|path>	Initialize with OpenAPI spec, learn patterns
/oas:sync	Generate/sync code based on OpenAPI spec
/oas:status	Quick status check using cache
/oas:diff	Compare spec changes
/oas:validate	Validate code matches spec
/oas:lint	Check spec + code consistency
/oas:analyze	Deep analysis of detected patterns

Key Features

1. Sample-Based Pattern Learning

Analyzes your existing API code to learn project patterns:

/oas:init ./openapi.json                        # Local file
/oas:init https://api.example.com/openapi.json  # Remote URL

📄 OpenAPI: My API v2.0.0 (25 endpoints)

🔍 Scanning for existing API code...
   Found 5 API files in src/entities/*/api/

📂 Detected patterns:
  ✓ HTTP client: createApi() (Axios wrapper)
  ✓ Data fetching: React Query v5 + createQuery helper
  ✓ Structure: FSD (Feature-Sliced Design)
  ✓ Naming: camelCase functions, PascalCase types

Generate code using these patterns?

2. Consistent Code Generation

Generates new API code using learned patterns:

/oas:sync --tag=publisher

Generated:
  ✓ src/entities/publisher/api/publisher-api.ts
  ✓ src/entities/publisher/api/publisher-queries.ts
  ✓ src/entities/publisher/api/publisher-mutations.ts
  ✓ src/entities/publisher/model/publisher-types.ts
  ✓ src/entities/publisher/config/publisher-api-paths.ts

3. Caching & Diff-Based Processing

Only processes changes to save tokens and time:

/oas:sync

✓ No spec changes (cache hint)
✓ Direct code-spec comparison complete
✓ No changes needed

# When changes exist
/oas:sync

Changes detected:
  +2 added, ~1 modified, -0 removed
  (148 unchanged - skipped)

Generating...
  ✓ POST /clips/{id}/render (new)
  ✓ GET /clips/{id}/status (new)
  ~ GET /users/{id} (updated: +preferences field)

4. Project-Standard Consistency Checks

Detects inconsistencies based on your project's majority patterns:

/oas:lint

Analyzing project patterns...
  Type naming: PascalCase (97.5%)
  Export style: export * (72.9%)
  Return types: Explicit (60.3%)

Inconsistencies found:
  🟡 upload-types.ts: 8 types using camelCase
     → Differs from project standard (PascalCase)

/oas:lint --fix

  ✓ Renamed 8 types to PascalCase
  ✓ Updated imports in 3 files
  ✓ TypeScript check passed

Command Reference

/oas:init

Initialize project and learn patterns.

/oas:init                      # Auto-detect patterns
/oas:init ./openapi.json       # Use local spec file
/oas:init https://api.com/spec # Use remote spec URL
/oas:init --force              # Overwrite existing config
/oas:init --interactive        # Skip auto-detection, configure manually
/oas:init --sample=path        # Specify sample file to learn from

/oas:sync

Generate or update code based on OpenAPI spec.

# Basic
/oas:sync                    # Default (Smart, 100% accuracy)
/oas:sync --dry-run          # Preview only, no file changes
/oas:sync --force            # Ignore cache, full regeneration
/oas:sync --trust-cache      # Trust cache mode (faster, 99% accuracy)
/oas:sync --offline          # Use cached spec only (no network)

# Filter by tag
/oas:sync --tag=users        # Specific tag only
/oas:sync --tag=users --tag=projects  # Multiple tags
/oas:sync --exclude-tag=internal      # Exclude tag

# Filter by endpoint
/oas:sync --endpoint="/api/v1/users/{id}"
/oas:sync --endpoint="/api/v1/clips/*"  # Wildcard

# Filter by change type
/oas:sync --only-added       # New endpoints only
/oas:sync --only-changed     # Modified endpoints only

# Filter by file type
/oas:sync --only-types       # Types only
/oas:sync --only-api         # API functions only
/oas:sync --only-hooks       # Hooks only

/oas:diff

Compare OpenAPI spec changes.

/oas:diff                    # Compare cached vs current
/oas:diff --remote           # Compare with remote spec
/oas:diff old.json new.json  # Compare two files
/oas:diff --breaking-only    # Show breaking changes only
/oas:diff --force            # Ignore cache, fetch fresh spec
/oas:diff --offline          # Use cached spec only (no network)
/oas:diff --tag=users        # Specific tag only
/oas:diff --exclude-tag=internal  # Exclude specific tag
/oas:diff --list-tags        # Show tags with change summary

/oas:validate

Validate code matches spec.

/oas:validate                # Basic validation
/oas:validate --strict       # Warnings treated as errors
/oas:validate --fix          # Auto-fix what's possible
/oas:validate --force        # Ignore cache, fetch fresh spec
/oas:validate --offline      # Use cached spec only (no network)
/oas:validate --tag=users    # Specific tag only
/oas:validate --quiet        # Errors only

/oas:lint

Check spec and code for consistency.

/oas:lint                    # Check spec + code
/oas:lint --spec             # Spec only
/oas:lint --code             # Code only
/oas:lint --fix              # Show fix suggestions
/oas:lint --rule=type-naming # Specific rule only
/oas:lint --severity=critical # Filter by severity
/oas:lint --ignore=pattern   # Ignore specific path/schema
/oas:lint --force            # Ignore cache, fetch fresh spec
/oas:lint --offline          # Use cached spec only (no network)

/oas:status

Quick status check from cache.

/oas:status                  # Instant status (~0.1s)
/oas:status --check-remote   # Check remote spec hash (~1s)
/oas:status --tag=users      # Status for specific tag
/oas:status --list-tags      # Show all tags with coverage
/oas:status --quiet          # Summary only
/oas:status --verbose        # Show detailed coverage breakdown

/oas:analyze

Deep analysis of detected patterns.

/oas:analyze                 # Full pattern analysis
/oas:analyze --verbose       # Show all file paths and code samples
/oas:analyze --domain=users  # Analyze specific domain only

Tag Filtering

Filter operations by OpenAPI tags. Tags are extracted from the tags field in each endpoint.

Discover Tags

# See all available tags
/oas:sync --list-tags

📋 Available Tags:

Tag              Endpoints   Status
─────────────────────────────────────
workspace        18          ⚠️ Partial (14/18)
user             12          ✅ Complete
billing          8           ❌ Missing
...

Filter by Tag

# Sync only specific tag
/oas:sync --tag=workspace

# Multiple tags (OR logic)
/oas:sync --tag=workspace --tag=billing

# Exclude tags
/oas:sync --exclude-tag=internal

# Combined
/oas:sync --tag=workspace --exclude-tag=deprecated

Tag Commands

Command	Example
/oas:sync	--tag=users, --exclude-tag=internal
/oas:diff	--tag=users, --list-tags
/oas:status	--tag=users, --list-tags
/oas:validate	--tag=users

Tag-Based Generation

When using --tag, only endpoints with matching tags are processed:

/oas:sync --tag=billing

Generated:
  src/entities/billing/
  ├── api/billing-api.ts        (8 functions)
  ├── api/billing-queries.ts    (8 hooks)
  ├── config/billing-api-paths.ts
  └── model/billing-types.ts    (12 types)

Sync Modes

Mode	Command	Speed	Accuracy	Use Case
Smart (default)	/oas:sync	Fast*	100%	Always recommended
Trust Cache	/oas:sync --trust-cache	Fast	99%*	Quick check needed
Force	/oas:sync --force	Slow	100%	Ignore cache, full regen

*Smart mode: HEAD request to check changes, full fetch only when needed

*Trust Cache may miss changes if server ETag/Last-Modified errors or cache corrupted

Interactive Selection

When running /oas:sync without flags and changes are detected, Claude will show a preview and ask for confirmation before generating code:

📊 Changes Detected:

NEW (3):
  1. POST /api/v1/clips/{id}/render (clips)
  2. GET  /api/v1/clips/{id}/status (clips)
  3. DELETE /api/v1/cache/{key} (cache)

CHANGED (2):
  4. GET /api/v1/users/{id} (users)
  5. POST /api/v1/projects (projects)

Proceed with generation?
(You can select specific items or proceed with all)

Response Options:

• "Yes" or "Proceed" - Process all changes
• "Only 1, 2" - Process specific numbered items
• "Only clips" - Process by tag name
• "Skip" or "No" - Cancel generation

Breaking Changes Detection

/oas:diff automatically detects breaking changes:

🚨 BREAKING CHANGES:

1. Required field added to request
   POST /api/v1/projects
   + workspaceId (required)
   → Existing client code needs modification

2. Field removed from response
   GET /api/v1/users/{id}
   - legacyToken
   → Check code using this field

3. Type changed
   GET /api/v1/users/{id}
   status: string → enum['active','inactive']
   → Verify type compatibility

4. Endpoint removed
   GET /api/v1/legacy/export
   → Remove usage code

For detailed migration strategies and handling breaking changes, see MIGRATION.md.

Generated File Structures

FSD (Feature-Sliced Design)

src/entities/{tag}/
├── api/
│   ├── {tag}-api.ts        # API functions
│   ├── {tag}-api-paths.ts  # Path constants
│   └── queries.ts          # React Query hooks
└── model/
    └── types.ts            # TypeScript types

Feature-based

src/features/{tag}/
├── api.ts          # API functions + paths
├── hooks.ts        # React Query hooks
└── types.ts        # TypeScript types

Flat

src/api/{tag}/
├── api.ts
├── hooks.ts
└── types.ts

Configuration

.openapi-sync.json

Note: Most values are auto-detected from your codebase by /oas:init. You only need to provide openapi.source and samples - everything else is learned from your existing code.

Minimal Config (Required Only)

{
  "openapi": {
    "source": "https://api.example.com/openapi.json"
  },
  "samples": {
    "api": "src/entities/user/api/user-api.ts"
  }
}

Full Config (Auto-Generated Example)

The following shows what /oas:init generates after scanning your codebase. All values below are examples - actual values are detected from YOUR project's code.

{
  "version": "1.0.0",

  "openapi": {
    "source": "https://api.example.com/openapi.json"
  },

  "samples": {
    "api": "src/entities/user/api/user-api.ts",
    "types": "src/entities/user/model/types.ts",
    "hooks": "src/entities/user/api/queries.ts",
    "keys": "src/entities/user/api/user-keys.ts"
  },

  "tagMapping": {
    "user-controller": "user",
    "project-controller": "project"
  },

  "ignore": [
    "/health",
    "/metrics",
    "/internal/*"
  ],

  "validation": {
    "ignorePaths": ["src/entities/legacy/*"]
  }
}

Note: project.* and patterns.* are auto-detected from samples and stored internally. You don't need to configure them manually.

Config Field Reference

Field	Required	Description
version		Config file version (e.g., "1.0.0")
openapi.source	✅	OpenAPI spec path or URL
samples.api	✅	API functions sample file path
samples.types		TypeScript types sample file path
samples.hooks		React Query/SWR hooks sample file path
samples.keys		Query key factory sample file path
tagMapping		Map OpenAPI tags to domain names (e.g., {"user-controller": "user"})
ignore		Endpoint paths to ignore (e.g., ["/health", "/internal/*"])
validation.ignorePaths		Glob patterns for paths to skip validation

Note: project.* and patterns.* are auto-detected from your samples and stored internally by /oas:init. Manual configuration is not needed.

Cache Files

.openapi-sync.cache.json  → Spec cache (hash, endpoints, schemas)
.openapi-sync.state.json  → Implementation state (coverage, timestamps)

Time Tracking Fields

File	Field	Description
cache.json	lastFetch	When the OpenAPI spec was last fetched from server
state.json	lastScan	When the codebase was last scanned for implementations
state.json	lastSync	When code was last generated by /oas:sync

Use /oas:status to view these timestamps.

Cache Invalidation

Cache is automatically invalidated when:

• --force flag is used
• Cache file is missing
• Cache version mismatch
• 24 hours elapsed (configurable)

Lint Rules

Spec Rules (10)

Rule	Description	Severity
response-key-consistency	List response key naming	warning
timestamp-naming	Timestamp field naming	warning
id-type-consistency	ID field type consistency	error
boolean-prefix	Boolean field prefixes	info
operationId-format	operationId format	warning
required-fields	Required field consistency	warning
enum-casing	Enum value casing	info
nullable-vs-optional	nullable vs optional usage	info
description-coverage	Description coverage %	info
path-naming	URL path naming patterns	warning

Code Rules (10)

Rule	Description	Severity
export-pattern-consistency	Barrel export patterns	warning
immutability-pattern	Object.freeze vs as const	warning
type-naming-convention	Type naming (PascalCase, etc.)	warning
api-function-parameter-style	API function params style	info
query-key-format	Query key naming format	warning
config-structure	Config file structure	info
barrel-export-completeness	Missing index.ts files	warning
file-naming-convention	File naming patterns	info
mutation-vs-query-separation	Mutation/Query file separation	warning
return-type-annotation	Explicit return types	warning

Note: Code rules use project-based detection. The majority pattern in your codebase becomes the "standard" - we find inconsistencies, not enforce external rules.

Philosophy

1. Sample-Based Learning

❌ "I'll generate FSD structure with Axios pattern"
✅ "I see how user-api.ts works, I'll make more like it"

2. Project-Standard Consistency

❌ "PascalCase is TypeScript standard, so you're wrong"
✅ "This project uses PascalCase 97%, so camelCase is inconsistent"

3. Accuracy > Speed

❌ Skip if cache hash matches (edge case risk)
✅ Cache is a hint, always verify with actual spec-code comparison (100% accuracy)

4. Incremental Changes

❌ Full regeneration every time
✅ Detect and process only changes (diff-based)

Error Handling

Error	Solution
Invalid OpenAPI spec	Check spec path, validate format
Pattern detection failed	Use --interactive mode
package.json not found	Run from project root
Config already exists	Use --force or choose merge
Cache corrupted	Auto-regenerated on next run

Supported Environments

• OpenAPI: 3.0.x, 3.1.x, Swagger 2.0
• Language: TypeScript
• HTTP Clients: Axios, Fetch, ky, others (auto-detected)
• Data Fetching: React Query, SWR, others (auto-detected)
• Frameworks: React, Vue, Angular, Svelte (auto-detected)
• Structure: FSD, Feature-based, Flat, others (auto-detected)

Security Flags

For development environments, additional flags are available:

Flag	Description	Use Case
--insecure	Skip SSL certificate verification	Self-signed certs in development
--allow-internal	Allow internal/private IP addresses	Local API servers

Examples:

# Access spec with self-signed certificate (development only)
/oas:init https://dev-api.local/openapi.json --insecure

# Access spec on internal network
/oas:init https://192.168.1.100/openapi.json --allow-internal

# Combine flags for local development
/oas:sync --allow-internal --insecure

Warning: These flags bypass security protections. Never use in production or with untrusted URLs. See SECURITY.md for detailed guidelines.

Troubleshooting

"No patterns detected"

# Provide sample manually
/oas:init --sample=src/api/user-api.ts

# Or use interactive mode
/oas:init --interactive

"Cache seems outdated"

# Force full sync
/oas:sync --force

# Or just check remote
/oas:status --check-remote

"Generated code doesn't match my style"

1. Check if sample file is correct in .openapi-sync.json
2. Run /oas:analyze to see detected patterns
3. Adjust patterns manually in config if needed

License

MIT