0
# CLI Usage
1

2
The swagger-typescript-api command-line interface provides full access to the code generation capabilities with comprehensive options for integration into build pipelines and development workflows.
3

4
## Installation
5

6
```bash
7
# Install globally
8
npm install -g swagger-typescript-api
9

10
# Install locally in project
11
npm install --save-dev swagger-typescript-api
12
```
13

14
## Command Structure
15

16
```bash { .api }
17
# Main command with subcommands
18
swagger-typescript-api [command] [options]
19
sta [command] [options]  # Short alias
20

21
# Available subcommands
22
swagger-typescript-api generate [options]           # Generate TypeScript API client
23
swagger-typescript-api generate-templates [options] # Generate EJS templates
24

25
# Help and version
26
swagger-typescript-api --help                       # Show help
27
swagger-typescript-api --version                    # Show version
28
```
29

30
## Generate Command
31

32
The main command for generating TypeScript API clients from OpenAPI specifications.
33

34
### Basic Usage
35

36
```bash { .api }
37
# Generate from local file
38
swagger-typescript-api generate --path ./openapi.json
39

40
# Generate from URL
41
swagger-typescript-api generate --path https://petstore.swagger.io/v2/swagger.json
42

43
# Generate with custom output
44
swagger-typescript-api generate --path ./api-spec.yaml --output ./src/api --name ApiClient.ts
45
```
46

47
### Core Options
48

49
```bash { .api }
50
# Input/Output Options
51
--path, -p <path>        # Path or URL to OpenAPI schema (required)
52
--output, -o <path>      # Output directory (default: "./")
53
--name, -n <filename>    # Output filename (default: "Api.ts")
54
--templates, -t <path>   # Custom templates directory
55

56
# HTTP Client Options
57
--axios                  # Use Axios HTTP client
58
--http-client <type>     # HTTP client type: "fetch" | "axios"
59

60
# Generation Options
61
--client                 # Generate API client class (default: true)
62
--responses, -r          # Generate response type definitions
63
--route-types            # Generate route type definitions
64
--modular                # Generate separate files for client, contracts, routes
65
```
66

67
### Advanced Options
68

69
```bash { .api }
70
# Type Generation Options
71
--add-readonly           # Generate readonly properties
72
--another-array-type     # Use Array<Type> instead of Type[]
73
--extract-enums          # Extract enums to TypeScript enum construction
74
--generate-union-enums   # Generate enums as union types (T1 | T2 | TN)
75
--enum-names-as-values   # Use x-enumNames as enum values
76

77
# Extraction Options
78
--extract-request-body   # Extract request body types to data contracts
79
--extract-response-body  # Extract response body types to data contracts
80
--extract-response-error # Extract response error types to data contracts
81
--extract-request-params # Extract request parameters to data contracts
82
--extract-responses      # Extract all responses from /components/responses
83

84
# Processing Options
85
--default-as-success, -d # Use "default" response status as success response
86
--patch                  # Fix small errors in swagger schema definition
87
--unwrap-response-data   # Unwrap data item from response
88
--disable-throw-on-error # Don't throw errors on non-successful responses
89

90
# Naming & Organization
91
--api-class-name <name>  # Name of the main API class (default: "Api")
92
--type-prefix <prefix>   # Prefix for generated type names
93
--type-suffix <suffix>   # Suffix for generated type names
94
--module-name-index <n>  # Path index for route module separation
95
--module-name-first-tag  # Use first tag for module names
96

97
# Code Style Options
98
--sort-types             # Sort data contracts alphabetically
99
--sort-routes            # Sort routes alphabetically
100
--single-http-client     # Allow HttpClient instance in Api constructor
101

102
# Output Options
103
--js                     # Generate JavaScript with declaration files
104
--clean-output           # Clean output directory before generation
105
--default-response <type># Default type for empty response schema (default: "void")
106
```
107

108
### Development Options
109

110
```bash { .api }
111
# Debug & Logging
112
--debug                  # Show detailed processing information
113
--silent                 # Output only errors to console
114

115
# Configuration
116
--custom-config <path>   # Path to custom configuration file
117
```
118

119
### Usage Examples
120

121
```bash
122
# Basic API generation
123
swagger-typescript-api generate --path ./openapi.json --output ./src/api
124

125
# Generate with Axios and response types
126
swagger-typescript-api generate \
127
  --path https://api.example.com/openapi.json \
128
  --output ./api \
129
  --axios \
130
  --responses \
131
  --route-types
132

133
# Generate modular structure with enums
134
swagger-typescript-api generate \
135
  --path ./api-spec.yaml \
136
  --output ./generated \
137
  --modular \
138
  --extract-enums \
139
  --extract-request-body \
140
  --extract-response-body
141

142
# Generate with custom naming and sorting
143
swagger-typescript-api generate \
144
  --path ./swagger.json \
145
  --name MyApiClient.ts \
146
  --api-class-name MyApi \
147
  --type-prefix API \
148
  --sort-types \
149
  --sort-routes
150

151
# Generate JavaScript output
152
swagger-typescript-api generate \
153
  --path ./openapi.json \
154
  --js \
155
  --output ./dist/api
156
```
157

158
## Generate Templates Command
159

160
Generate customizable EJS templates for API code generation.
161

162
### Basic Usage
163

164
```bash { .api }
165
# Generate default templates
166
swagger-typescript-api generate-templates --output ./my-templates
167

168
# Generate modular templates
169
swagger-typescript-api generate-templates \
170
  --output ./templates \
171
  --modular \
172
  --http-client axios
173
```
174

175
### Template Options
176

177
```bash { .api }
178
# Output Options
179
--output, -o <path>      # Output directory for templates
180
--clean-output           # Clean output directory before generation
181
--rewrite, -r            # Overwrite existing templates
182

183
# Template Configuration
184
--http-client <type>     # HTTP client type for templates: "fetch" | "axios"
185
--modular                # Generate modular template structure
186

187
# Debug Options
188
--debug                  # Show detailed processing information
189
--silent                 # Output only errors to console
190
```
191

192
### Template Usage Examples
193

194
```bash
195
# Generate Fetch-based templates
196
swagger-typescript-api generate-templates \
197
  --output ./templates/fetch \
198
  --http-client fetch
199

200
# Generate Axios modular templates
201
swagger-typescript-api generate-templates \
202
  --output ./templates/axios-modular \
203
  --http-client axios \
204
  --modular \
205
  --clean-output
206

207
# Use custom templates in generation
208
swagger-typescript-api generate \
209
  --path ./openapi.json \
210
  --templates ./my-custom-templates \
211
  --output ./api
212
```
213

214
## Configuration Files
215

216
### Custom Configuration
217

218
Create a custom configuration file for complex setups:
219

220
```typescript
221
// swagger-typescript-api.config.js
222
export default {
223
  hooks: {
224
    onCreateRoute: (routeData) => {
225
      // Custom route processing
226
      return routeData;
227
    },
228
    onFormatTypeName: (typeName) => {
229
      // Custom type naming
230
      return `I${typeName}`;
231
    }
232
  },
233
  primitiveTypeConstructs: (struct) => ({
234
    ...struct,
235
    string: {
236
      ...struct.string,
237
      'date-time': () => 'Date',
238
    }
239
  })
240
};
241
```
242

243
```bash
244
# Use custom configuration
245
swagger-typescript-api generate \
246
  --path ./openapi.json \
247
  --custom-config ./swagger-typescript-api.config.js
248
```
249

250
## Integration Examples
251

252
### NPM Scripts
253

254
```json
255
{
256
  "scripts": {
257
    "api:generate": "swagger-typescript-api generate --path ./api-spec.json --output ./src/api",
258
    "api:dev": "swagger-typescript-api generate --path http://localhost:3000/api-docs --output ./src/api --debug",
259
    "api:build": "swagger-typescript-api generate --path ./openapi.yaml --output ./dist/api --js --clean-output"
260
  }
261
}
262
```
263

264
### CI/CD Pipeline
265

266
```yaml
267
# GitHub Actions example
268
- name: Generate API Client
269
  run: |
270
    npx swagger-typescript-api generate \
271
      --path https://api.production.com/openapi.json \
272
      --output ./src/generated-api \
273
      --responses \
274
      --route-types \
275
      --clean-output
276
```
277

278
### Build Process Integration
279

280
```bash
281
#!/bin/bash
282
# build-api.sh
283

284
# Download latest API spec
285
curl -o ./temp-spec.json https://api.example.com/openapi.json
286

287
# Generate TypeScript client
288
swagger-typescript-api generate \
289
  --path ./temp-spec.json \
290
  --output ./src/api \
291
  --modular \
292
  --extract-enums \
293
  --sort-types \
294
  --clean-output
295

296
# Clean up
297
rm ./temp-spec.json
298

299
echo "API client generated successfully"
300
```
301

302
## Error Handling
303

304
The CLI provides detailed error messages and exit codes:
305

306
```bash
307
# Check exit code
308
swagger-typescript-api generate --path ./invalid.json
309
echo $? # Non-zero exit code on failure
310
```
311

312
**Common Error Scenarios:**
313
- **Exit Code 1**: Schema file not found or network error
314
- **Exit Code 2**: Invalid OpenAPI schema format  
315
- **Exit Code 3**: Template processing error
316
- **Exit Code 4**: File system permission error
317

318
**Debug Mode:**
319
```bash
320
# Enable debug output for troubleshooting
321
swagger-typescript-api generate --path ./schema.json --debug
322
```