Generate TypeScript Models
Converts OpenAPI/Swagger schemas into TypeScript declarations (interfaces, enums, and index barrel file).
Overview
Generates TypeScript interfaces and enums from OpenAPI/Swagger specifications with automatic barrel file organization. Supports both OpenAPI 3.x (components/schemas ) and Swagger 2.0 (definitions ).
Core principle: Parse schemas → Apply type mappings → Generate one file per schema → Create barrel file
When to Use
Use this skill when:
-
You have an OpenAPI or Swagger specification file
-
Need TypeScript type safety for API models
-
Want automatic barrel file (index.ts) generation
-
Generating initial types or regenerating from updated specs
-
Need custom type mappings or enum protection
Do NOT use when:
-
Spec file is not JSON format → Use download-swagger-file skill first
-
Need single-file output → This skill only supports folder mode
-
Spec has no schemas → Verify spec contains components/schemas or definitions
Core Pattern
Before:
// openapi.json { "components": { "schemas": { "User": { "type": "object", "properties": { "id": {"type": "integer"}, "name": {"type": "string"} } } } } }
After:
// types/User.ts export interface User { id: number; name: string; }
// types/index.ts export * from './User';
Workflow: Parse spec → Extract schemas → Apply mappings → Generate files → Create barrel
Usage
node skills/generate-ts-models/scripts/generate.js <spec-file> [output-dir] [options]
Arguments:
-
spec-file
-
Path to OpenAPI JSON (required)
-
output-dir
-
Output directory (optional, defaults to ./types )
-
--enum-protect <strategy>
-
See Enum Protection
Examples:
Default settings
node skills/generate-ts-models/scripts/generate.js ./swagger.json
Custom output directory
node skills/generate-ts-models/scripts/generate.js ./swagger.json ./src/types/
With enum protection
node skills/generate-ts-models/scripts/generate.js ./swagger.json ./types --enum-protect preserve-manual
Output Structure
Generates one .ts file per schema plus an index.ts barrel file:
./types/ ├── User.ts ├── UserStatus.ts └── index.ts
Generated content:
File Type
User.ts
interface
UserStatus.ts
enum
index.ts
barrel file (auto-generated exports)
See Configuration for customization.
Enum Protection
Preserve manually edited enum keys when regenerating. See Enum Protection for:
-
Protection strategies (none , preserve-manual , always )
-
@preserve-manual marker format
-
Workflow examples
Troubleshooting
Common issues:
-
INVALID_JSON - Check spec file is valid JSON
-
NO_SCHEMAS - Verify spec has components/schemas or definitions
-
PERMISSION_DENIED - Check write permissions on output directory
See Error Codes for complete reference.
Common Mistakes
Mistake Symptoms Fix
Passing .ts file as output path Error: SINGLE_FILE_NOT_SUPPORTED
Use directory path, not file path
Expecting single-file output All schemas in one .ts file This skill generates one file per schema
Not creating output directory Error: PERMISSION_DENIED
Create directory first: mkdir -p ./types
Forgetting barrel file import Can't find types Import from barrel: import { User } from './types'
Present Results to User
Generated TypeScript models to ./src/types/ :
- 20 files (15 interfaces, 4 enums, 1 index.ts)