Initialize OpenAPI sync - learns your project patterns automatically
Initialize OpenAPI sync by learning your project's patterns and generating configuration.
/plugin marketplace add jhlee0409/claude-plugins/plugin install oas@jhlee0409-pluginsInitialize OpenAPI sync by learning your project's existing patterns. Works with ANY codebase.
/oas:init <spec-url-or-path>
Examples:
# From URL
/oas:init https://api.example.com/openapi.json
# From local file
/oas:init ./docs/openapi.yaml
When /oas:init is invoked, Claude MUST perform these steps in order:
.openapi-sync.jsonIMPORTANT: Always start by asking the user for the OpenAPI spec location.
๐ OpenAPI Sync Initialization
Please enter the OpenAPI spec URL or file path:
Examples:
โข https://api.example.com/openapi.json
โข ./openapi.json
โข ./docs/swagger.yaml
If user provided argument with command, use that directly. If not, prompt for input before proceeding.
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ /oas:init โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ 1. Get OpenAPI spec location โ
โ 2. Fetch & cache spec (cache-manager) โ
โ 3. Validate spec (openapi-parser) โ
โ 4. Detect framework (package.json) โ
โ 5. Find existing API code (sample discovery) โ
โ 6. Analyze samples OR ask user โ
โ 7. Generate .openapi-sync.json โ
โ 8. Security check (.gitignore) โ
โ 9. Show summary โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Supported sources:
File: ./openapi.json, ./docs/swagger.yaml
URL: https://api.example.com/openapi.json
If argument provided:
http:// or https:// โ Fetch from URL
Otherwise โ Read as local file
If no argument:
1. Search for openapi.json, swagger.json locally
2. If found, ask to confirm usage
3. If not found, request path/URL input
Use cache-manager skill to fetch and cache:
Invoke skill: cache-manager
1. Fetch spec from source (URL or local file)
2. Validate basic structure (has openapi/swagger field)
3. Write .openapi-sync.cache.json immediately
This ensures /oas:sync doesn't need to refetch.
Output:
๐ฅ Fetching spec from https://api.example.com/openapi.json...
โ
Spec cached (150 endpoints, 45 schemas)
Use openapi-parser skill:
Invoke skill: openapi-parser
- Verify OpenAPI 3.x or Swagger 2.x structure
- Extract title, version, endpoints
- Parse schemas and validate references
Read package.json:
// Detect ecosystem
const framework = detectFramework(packageJson)
// Output example:
{
framework: "react", // react, vue, angular, svelte, etc.
language: "typescript", // typescript or javascript
httpClient: "axios", // from dependencies
dataFetching: "react-query" // from dependencies
}
Report:
๐ฆ package.json analysis:
Framework: React + TypeScript
HTTP Client: axios
Data Fetching: @tanstack/react-query v5
Use pattern-detector skill:
Invoke skill: pattern-detector
Search for existing API code:
Possible outcomes:
OUTCOME A: Samples found
โ "Found 5 API files in src/entities/*/api/"
โ Proceed to sample analysis
OUTCOME B: No samples found
โ "No existing API code found"
โ Go to interactive mode
Analyze discovered files:
Analyzing samples...
๐ Structure detected:
Pattern: src/entities/{domain}/api/
Samples: user, project, clip (3 domains)
๐ HTTP Client:
Type: Custom wrapper (createApi)
Location: src/shared/api/create-api.ts
Pattern: createApi().{method}<T>(path)
๐ฆ Data Fetching:
Library: React Query v5
Pattern: Query Key Factory
Hooks: Separate file (queries.ts)
๐ Types:
Location: src/entities/{domain}/model/types.ts
Style: interface
Naming: {Entity}, {Operation}Request, {Operation}Response
๐ท๏ธ Naming:
Functions: get{Entity}, create{Entity}
Hooks: use{Entity}, useCreate{Entity}
Files: {domain}-api.ts, queries.ts, types.ts
Ask confirmation:
Generate code using these patterns?
(Let me know if you'd like any changes)
Ask user for guidance:
Q1: "Where should API code be generated?"
Options:
- src/api/{domain}/ (flat)
- src/features/{domain}/api/ (feature-based)
- src/entities/{domain}/api/ (FSD)
- Custom path
Q2: "Which HTTP client are you using?"
Options (based on package.json):
- Axios (detected)
- Fetch (native)
- Other
Q3: "Are you using a data fetching library?"
Options (based on package.json):
- React Query (detected)
- SWR
- None
Q4: "Do you have sample code to reference?"
- Yes โ "Please provide the file path" OR "Paste the code"
- No โ Use framework defaults
Alternative:
"Paste sample code and I'll replicate that style:"
[User pastes code]
โ Analyze pasted code
โ Extract patterns
Create .openapi-sync.json:
Note:
project.*andpatterns.*are auto-detected from samples and stored internally. Only essential fields are saved to the config file.
{
"version": "1.0.0",
"openapi": {
"source": "./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": {},
"ignore": [
"/health",
"/metrics",
"/internal/*"
],
"validation": {
"ignorePaths": []
}
}
Check .gitignore for cache files:
1. Check if .gitignore exists
2. Check if cache files are in .gitignore:
- .openapi-sync.cache.json
- .openapi-sync.state.json
3. If not in .gitignore:
โ ๏ธ Warning: Cache files should be in .gitignore
Add these lines to .gitignore:
# OpenAPI Sync cache files (contain potentially sensitive data)
.openapi-sync.cache.json
.openapi-sync.state.json
4. Ask user: "Add these entries to .gitignore? [y/n]"
- If yes โ Append to .gitignore
- If no โ Show warning and continue
For more security guidelines, see ../docs/SECURITY.md.
โ
OpenAPI Sync initialization complete
๐ OpenAPI Spec:
My API v2.0.0
25 endpoints, 8 tags
Source: ./openapi.json
๐ Detected patterns:
Structure: FSD (Feature-Sliced Design)
HTTP: createApi() (custom Axios wrapper)
State: React Query v5 (factory pattern)
Types: interface, separate files
๐ Sample code:
API: src/entities/user/api/user-api.ts
Types: src/entities/user/model/types.ts
Hooks: src/entities/user/api/queries.ts
๐ Files created:
.openapi-sync.json (config)
.openapi-sync.cache.json (spec cache)
๐ Next steps:
/oas:analyze - Detailed pattern analysis
/oas:sync - Start code generation
/oas:sync --dry-run - Preview files to generate
OpenAPI spec error:
โ "Invalid OpenAPI spec: {error}"
โ "Please check the spec path"
Pattern detection failed:
โ Switch to interactive mode
โ "Could not detect patterns automatically. Let me ask a few questions."
package.json not found:
โ "Cannot find package.json. Please run from project root."
Existing config file:
โ ".openapi-sync.json already exists."
โ Ask user: Overwrite or merge with existing config?
--force: Overwrite existing config--interactive: Skip auto-detection and configure manually--sample=path: Specify a particular sample file