0
# Types & Interfaces
1

2
Complete TypeScript type definitions for swagger-typescript-api, providing full type safety for all configuration options, return values, and customization hooks.
3

4
## Core Types
5

6
### HTTP Client Types
7

8
```typescript { .api }
9
type HttpClientType = "fetch" | "axios";
10
```
11

12
### File Information
13

14
```typescript { .api }
15
interface FileInfo {
16
  /** File name without extension (e.g., "Api") */
17
  fileName: string;
18
  /** File extension (e.g., ".ts", ".d.ts") */
19
  fileExtension: string;
20
  /** Generated file content */
21
  fileContent: string;
22
}
23
```
24

25
### Generation Output
26

27
```typescript { .api }
28
interface GenerateApiOutput {
29
  /** Final configuration used for generation */
30
  configuration: GenerateApiConfiguration;
31
  /** Array of generated files with content */
32
  files: FileInfo[];
33
  /** Function to write files to disk */
34
  createFile: (params: CreateFileParams) => void;
35
  /** Function to render EJS templates with data */
36
  renderTemplate: (
37
    templateContent: string,
38
    data: Record<string, unknown>,
39
    etaOptions?: Partial<EtaConfig>
40
  ) => Promise<string> | string;
41
  /** Function to retrieve template content */
42
  getTemplate: (params: GetTemplateParams) => string;
43
  /** Function to format TypeScript code */
44
  formatTSContent: (content: string) => Promise<string>;
45
}
46

47
interface CreateFileParams {
48
  path: string;
49
  fileName: string;
50
  content: string;
51
  withPrefix: boolean;
52
}
53

54
interface GetTemplateParams {
55
  fileName?: string;
56
  name?: string;
57
  path?: string;
58
}
59
```
60

61
### Template Generation Output
62

63
```typescript { .api }
64
interface GenerateTemplatesOutput {
65
  /** Array of generated template files */
66
  files: FileInfo[];
67
  /** Function to write template files to disk */
68
  createFile: (params: CreateFileParams) => void;
69
}
70
```
71

72
## Configuration Types
73

74
### Complete Configuration
75

76
```typescript { .api }
77
interface GenerateApiConfiguration {
78
  /** API metadata from OpenAPI specification */
79
  apiConfig: ApiConfig;
80
  /** Generation configuration options */
81
  config: GenerationConfig;
82
  /** Generated model type definitions */
83
  modelTypes: ModelType[];
84
  /** Parsed route information */
85
  routes: RouteInfo;
86
  /** Utility functions for template processing */
87
  utils: TemplateUtils;
88
  /** Flags for different generation aspects */
89
  hasFormDataRoutes: boolean;
90
  hasSecurityRoutes: boolean;
91
  hasQueryRoutes: boolean;
92
  generateResponses: boolean;
93
  /** Request configuration for schema fetching */
94
  requestOptions?: Partial<RequestInit>;
95
}
96

97
interface ApiConfig {
98
  /** Base URL from OpenAPI specification */
99
  baseUrl: string;
100
  /** API title from specification */
101
  title: string;
102
  /** API version from specification */
103
  version: string;
104
  /** Description split into lines */
105
  description: string[];
106
  /** Flag indicating if description is present */
107
  hasDescription: boolean;
108
}
109
```
110

111
### Generation Configuration
112

113
```typescript { .api }
114
interface GenerationConfig {
115
  /** Input/Output Options */
116
  input: string;
117
  url: string;
118
  spec: unknown;
119
  output: string | false;
120
  fileName: string;
121
  templates: string;
122
  modular: boolean;
123
  
124
  /** HTTP Client Configuration */
125
  httpClientType: HttpClientType;
126
  singleHttpClient: boolean;
127
  
128
  /** Generation Flags */
129
  generateClient: boolean;
130
  generateResponses: boolean;
131
  generateRouteTypes: boolean;
132
  generateUnionEnums: boolean;
133
  
134
  /** Type Generation Options */
135
  addReadonly: boolean;
136
  anotherArrayType: boolean;
137
  extractEnums: boolean;
138
  extractRequestBody: boolean;
139
  extractResponseBody: boolean;
140
  extractResponseError: boolean;
141
  extractRequestParams: boolean;
142
  extractResponses: boolean;
143
  
144
  /** Processing Options */
145
  defaultResponseAsSuccess: boolean;
146
  defaultResponseType: string;
147
  disableThrowOnError: boolean;
148
  patch: boolean;
149
  unwrapResponseData: boolean;
150
  
151
  /** Naming Options */
152
  apiClassName: string;
153
  typePrefix: string;
154
  typeSuffix: string;
155
  enumKeyPrefix: string;
156
  enumKeySuffix: string;
157
  fixInvalidTypeNamePrefix: string;
158
  fixInvalidEnumKeyPrefix: string;
159
  
160
  /** Organization Options */
161
  moduleNameIndex: number;
162
  moduleNameFirstTag: boolean;
163
  sortTypes: boolean;
164
  sortRoutes: boolean;
165
  
166
  /** Output Options */
167
  cleanOutput: boolean;
168
  toJS: boolean;
169
  silent: boolean;
170
  debug: boolean;
171
  
172
  /** Advanced Configuration */
173
  hooks: Partial<Hooks>;
174
  primitiveTypeConstructs?: (struct: PrimitiveTypeStruct) => Partial<PrimitiveTypeStruct>;
175
  codeGenConstructs?: (struct: CodeGenConstruct) => Partial<CodeGenConstruct>;
176
  customTranslator?: new () => Translator;
177
  schemaParsers?: Partial<SchemaParserMap>;
178
  extractingOptions: Partial<ExtractingOptions>;
179
  
180
  /** Internal Configuration */
181
  version: string;
182
  constants: typeof CONSTANTS;
183
  compilerTsConfig: Record<string, unknown>;
184
  successResponseStatusRange: [number, number];
185
  templatePaths: TemplatePaths;
186
  templatesToRender: TemplatesToRender;
187
  fileNames: FileNames;
188
  internalTemplateOptions: InternalTemplateOptions;
189
}
190
```
191

192
### Schema and Route Types
193

194
```typescript { .api }
195
interface SchemaComponent {
196
  /** Schema reference path */
197
  $ref: string;
198
  /** Generated type name */
199
  typeName: string;
200
  /** Original schema data */
201
  rawTypeData?: RawTypeData;
202
  /** Component category */
203
  componentName: "schemas" | "paths";
204
  /** Parsed type information */
205
  typeData: ParsedSchema<SchemaContent> | null;
206
}
207

208
interface ParsedSchema<C> {
209
  $parsedSchema: boolean;
210
  schemaType: string;
211
  type: string;
212
  typeIdentifier: string;
213
  name: string;
214
  description?: string;
215
  allFieldsAreOptional?: boolean;
216
  content: C;
217
  isExtractedRequestParams?: boolean;
218
  isExtractedRequestBody?: boolean;
219
  isExtractedResponseBody?: boolean;
220
  isExtractedResponseError?: boolean;
221
}
222

223
interface ParsedRoute {
224
  /** Unique route identifier */
225
  id: string;
226
  /** Route namespace/module */
227
  namespace: string;
228
  /** Route parameters */
229
  routeParams?: Record<string, any>;
230
  /** Request body information */
231
  requestBodyInfo?: RequestBodyInfo;
232
  /** Response body information */
233
  responseBodyInfo?: ResponseBodyInfo;
234
  /** Specific route arguments */
235
  specificArgs?: Record<string, any>;
236
  /** Request information */
237
  request: ParsedRouteRequest;
238
  /** Response information */
239
  response: ParsedRouteResponse;
240
  /** Route naming information */
241
  routeName: RouteNameInfo;
242
  /** Original route data */
243
  raw: RawRouteInfo;
244
}
245

246
interface ModelType {
247
  /** Type identifier */
248
  typeIdentifier: string;
249
  /** Type name */
250
  name: string;
251
  /** Raw content string */
252
  rawContent: string;
253
  /** Type description */
254
  description: string;
255
  /** Formatted content */
256
  content: string;
257
}
258
```
259

260
### Additional Helper Types
261

262
```typescript { .api }
263
interface RawTypeData {
264
  type: string;
265
  required?: string[];
266
  properties?: Record<string, {
267
    name?: string;
268
    type: string;
269
    required: boolean;
270
    $parsed?: SchemaTypePrimitiveContent;
271
  }>;
272
  discriminator?: {
273
    propertyName?: string;
274
  };
275
  $parsed: ParsedSchema<SchemaTypeObjectContent | SchemaTypeEnumContent | SchemaTypePrimitiveContent>;
276
}
277

278
interface HeaderInfo {
279
  /** Header name */
280
  name: string | null;
281
  /** Whether header is optional */
282
  optional: boolean | undefined;
283
  /** Header type definition */
284
  type: Record<string, any>;
285
}
286

287
interface PayloadInfo {
288
  /** Payload parameter name */
289
  name: string | null;
290
  /** Whether payload is optional */
291
  optional?: boolean;
292
  /** Payload type */
293
  type: string;
294
}
295

296
interface RequestBodyInfo {
297
  /** Parameter name for request body */
298
  paramName: any;
299
  /** Content types accepted */
300
  contentTypes: any[];
301
  /** Content kind */
302
  contentKind: string;
303
  /** Request body schema */
304
  schema: any;
305
  /** Request body type */
306
  type: any;
307
  /** Whether request body is required */
308
  required: any;
309
}
310

311
interface ResponseBodyInfo {
312
  /** Response content types */
313
  contentTypes: any[];
314
  /** Response definitions */
315
  responses: any[];
316
  /** Success response info */
317
  success?: Record<string, any>;
318
  /** Error response info */
319
  error?: Record<string, any>;
320
  /** Full response info */
321
  full?: Record<string, any>;
322
}
323

324
interface CodeGenProcess {
325
  /** Code generation process methods and properties */
326
  start(): Promise<any>;
327
}
328

329
interface SchemaTypePrimitiveContent {
330
  $parsedSchema: boolean;
331
  schemaType: string;
332
  type: string;
333
  typeIdentifier: string;
334
  name?: unknown;
335
  description: string;
336
  content: string;
337
}
338

339
interface SchemaTypeObjectContent extends Array<{
340
  $$raw: {
341
    type: string;
342
    required: boolean;
343
    $parsed: SchemaTypePrimitiveContent;
344
  };
345
  isRequired: boolean;
346
  field: string;
347
}> {}
348

349
interface SchemaTypeEnumContent extends Array<{
350
  key: string;
351
  type: string;
352
  value: string;
353
}> {}
354

355
type SchemaContent = 
356
  | SchemaTypeObjectContent 
357
  | SchemaTypeEnumContent 
358
  | SchemaTypePrimitiveContent;
359

360
interface RouteInfo {
361
  /** Routes not organized into modules */
362
  outOfModule: ParsedRoute[];
363
  /** Routes organized by modules */
364
  combined?: {
365
    moduleName: string;
366
    routes: ParsedRoute[];
367
  }[];
368
}
369

370
interface SchemaParserMap {
371
  complexOneOf?: MonoSchemaParser;
372
  complexAllOf?: MonoSchemaParser;
373
  complexAnyOf?: MonoSchemaParser;
374
  complexNot?: MonoSchemaParser;
375
  enum?: MonoSchemaParser;
376
  object?: MonoSchemaParser;
377
  complex?: MonoSchemaParser;
378
  primitive?: MonoSchemaParser;
379
  discriminator?: MonoSchemaParser;
380
  array?: MonoSchemaParser;
381
}
382

383
interface MonoSchemaParser {
384
  /** Schema parser function */
385
  parse(schemaParserInput: any): any;
386
}
387

388
interface SchemaParser {
389
  /** Parse schema with given input */
390
  parseSchema(schema: Record<string, unknown>): any;
391
}
392

393
abstract class Translator {
394
  /** Abstract translator class for TypeScript to other languages */
395
  abstract translate(content: string): string;
396
}
397
```
398

399
### Request and Response Types
400

401
```typescript { .api }
402
interface ParsedRouteRequest {
403
  contentTypes?: string[];
404
  formData?: boolean;
405
  headers?: HeaderInfo;
406
  isQueryBody?: boolean;
407
  method?: string;
408
  parameters?: Record<string, unknown>[];
409
  path?: string;
410
  pathParams?: Record<string, unknown>;
411
  payload?: PayloadInfo;
412
  query?: Record<string, unknown>;
413
  requestParams?: Record<string, unknown> | null;
414
  security?: boolean;
415
}
416

417
interface ParsedRouteResponse {
418
  contentTypes?: string[];
419
  errorType?: string;
420
  fullTypes?: string;
421
  type?: string;
422
}
423

424
interface RequestResponseInfo {
425
  /** Content types accepted/returned */
426
  contentTypes: string[];
427
  /** Content category */
428
  contentKind: RequestContentKind;
429
  /** TypeScript type */
430
  type: string;
431
  /** Description from OpenAPI */
432
  description: string;
433
  /** HTTP status code */
434
  status: string | number;
435
  /** Whether this is a success response */
436
  isSuccess: boolean;
437
}
438

439
enum RequestContentKind {
440
  JSON = "JSON",
441
  URL_ENCODED = "URL_ENCODED",
442
  FORM_DATA = "FORM_DATA",
443
  IMAGE = "IMAGE",
444
  OTHER = "OTHER",
445
  TEXT = "TEXT"
446
}
447
```
448

449
### Route Information Types
450

451
```typescript { .api }
452
interface RouteNameInfo {
453
  /** Generated usage name */
454
  usage: string;
455
  /** Original name from OpenAPI */
456
  original: string;
457
  /** Whether name is duplicated */
458
  duplicate: boolean;
459
}
460

461
interface RawRouteInfo {
462
  /** OpenAPI operationId */
463
  operationId: string;
464
  /** HTTP method */
465
  method: string;
466
  /** Route path */
467
  route: string;
468
  /** Module name for organization */
469
  moduleName: string;
470
  /** Response type information */
471
  responsesTypes: RequestResponseInfo[];
472
  /** Route description */
473
  description?: string;
474
  /** OpenAPI tags */
475
  tags?: string[];
476
  /** Route summary */
477
  summary?: string;
478
  /** OpenAPI responses object */
479
  responses?: import("swagger-schema-official").Spec["responses"];
480
  /** Produced content types */
481
  produces?: string[];
482
  /** Request body definition */
483
  requestBody?: object;
484
  /** Consumed content types */
485
  consumes?: string[];
486
}
487

488
interface PathArgInfo {
489
  /** Parameter name */
490
  name: string;
491
  /** Whether parameter is optional */
492
  optional: boolean;
493
  /** Parameter type */
494
  type: string;
495
  /** Parameter description */
496
  description?: string;
497
}
498
```
499

500
## Customization Types
501

502
### Hooks Interface
503

504
```typescript { .api }
505
interface Hooks {
506
  /** Called before processing route path */
507
  onPreBuildRoutePath?: (routePath: string) => string | undefined;
508
  
509
  /** Called after processing route path */
510
  onBuildRoutePath?: (data: BuildRoutePath) => BuildRoutePath | undefined;
511
  
512
  /** Called before inserting path parameter */
513
  onInsertPathParam?: (
514
    paramName: string,
515
    index: number,
516
    arr: BuildRouteParam[],
517
    resultRoute: string
518
  ) => string | undefined;
519
  
520
  /** Called after parsing schema component */
521
  onCreateComponent?: (component: SchemaComponent) => SchemaComponent | undefined;
522
  
523
  /** Called before parsing any schema */
524
  onPreParseSchema?: (
525
    originalSchema: unknown,
526
    typeName: string,
527
    schemaType: string
528
  ) => undefined;
529
  
530
  /** Called after parsing any schema */
531
  onParseSchema?: (
532
    originalSchema: unknown,
533
    parsedSchema: unknown
534
  ) => unknown | undefined;
535
  
536
  /** Called after creating route (can return false to ignore route) */
537
  onCreateRoute?: (routeData: ParsedRoute) => ParsedRoute | false | undefined;
538
  
539
  /** Called at initialization */
540
  onInit?: <C extends GenerationConfig>(
541
    configuration: C,
542
    codeGenProcess: CodeGenProcess
543
  ) => C | undefined;
544
  
545
  /** Called before preparing configuration for templates */
546
  onPrepareConfig?: <C extends GenerateApiConfiguration>(
547
    currentConfiguration: C
548
  ) => C | undefined;
549
  
550
  /** Called when creating route names */
551
  onCreateRouteName?: (
552
    routeNameInfo: RouteNameInfo,
553
    rawRouteInfo: RawRouteInfo
554
  ) => RouteNameInfo | undefined;
555
  
556
  /** Called when creating request parameters */
557
  onCreateRequestParams?: (
558
    rawType: SchemaComponent["rawTypeData"]
559
  ) => SchemaComponent["rawTypeData"] | undefined;
560
  
561
  /** Called when formatting type names */
562
  onFormatTypeName?: (
563
    typeName: string,
564
    rawTypeName?: string,
565
    schemaType?: "type-name" | "enum-key"
566
  ) => string | undefined;
567
  
568
  /** Called when formatting route names */
569
  onFormatRouteName?: (
570
    routeInfo: RawRouteInfo,
571
    templateRouteName: string
572
  ) => string | undefined;
573
}
574
```
575

576
### Type Construction Types
577

578
```typescript { .api }
579
type PrimitiveTypeStruct = Record<
580
  "integer" | "number" | "boolean" | "object" | "file" | "string" | "array",
581
  | string
582
  | ({ $default: PrimitiveTypeStructValue } & Record<string, PrimitiveTypeStructValue>)
583
>;
584

585
type PrimitiveTypeStructValue =
586
  | string
587
  | ((schema: Record<string, unknown>, parser: SchemaParser) => string);
588

589
interface CodeGenConstruct {
590
  Keyword: {
591
    Number: string;
592
    String: string;
593
    Boolean: string;
594
    Any: string;
595
    Void: string;
596
    Unknown: string;
597
    Null: string;
598
    Undefined: string;
599
    Object: string;
600
    File: string;
601
    Date: string;
602
    Type: string;
603
    Enum: string;
604
    Interface: string;
605
    Array: string;
606
    Record: string;
607
    Intersection: string;
608
    Union: string;
609
  };
610
  CodeGenKeyword: {
611
    UtilRequiredKeys: string;
612
  };
613
  ArrayType: (content: unknown) => string;
614
  StringValue: (content: unknown) => string;
615
  BooleanValue: (content: unknown) => string;
616
  NumberValue: (content: unknown) => string;
617
  NullValue: (content: unknown) => string;
618
  UnionType: (content: unknown) => string;
619
  ExpressionGroup: (content: unknown) => string;
620
  IntersectionType: (content: unknown) => string;
621
  RecordType: (content: unknown) => string;
622
  TypeField: (content: unknown) => string;
623
  InterfaceDynamicField: (content: unknown) => string;
624
  EnumUsageKey: (enumStruct: unknown, key: unknown) => string;
625
  EnumField: (content: unknown) => string;
626
  EnumFieldDescription: (content: unknown) => string;
627
  EnumFieldsWrapper: (content: unknown) => string;
628
  ObjectWrapper: (content: unknown) => string;
629
  MultilineComment: (content: unknown) => string;
630
  TypeWithGeneric: (content: unknown) => string;
631
  Tuple: (content: unknown) => string;
632
}
633
```
634

635
### Extraction Options
636

637
```typescript { .api }
638
interface ExtractingOptions {
639
  requestBodySuffix: string[];
640
  responseBodySuffix: string[];
641
  responseErrorSuffix: string[];
642
  requestParamsSuffix: string[];
643
  enumSuffix: string[];
644
  discriminatorMappingSuffix: string[];
645
  discriminatorAbstractPrefix: string[];
646
  requestBodyNameResolver: (name: string, reservedNames: string) => string | undefined;
647
  responseBodyNameResolver: (name: string, reservedNames: string) => string | undefined;
648
  responseErrorNameResolver: (name: string, reservedNames: string) => string | undefined;
649
  requestParamsNameResolver: (name: string, reservedNames: string) => string | undefined;
650
  enumNameResolver: (name: string, reservedNames: string) => string | undefined;
651
  discriminatorMappingNameResolver: (name: string, reservedNames: string) => string | undefined;
652
  discriminatorAbstractResolver: (name: string, reservedNames: string) => string | undefined;
653
}
654
```
655

656
## Utility Types
657

658
### Template Utilities
659

660
```typescript { .api }
661
interface TemplateUtils {
662
  formatDescription: (description: string, inline?: boolean) => string;
663
  internalCase: (value: string) => string;
664
  pascalCase: (value: string) => string;
665
  getInlineParseContent: (rawTypeData: RawTypeData, typeName?: string) => string;
666
  getParseContent: (rawTypeData: RawTypeData, typeName?: string) => ModelType;
667
  getComponentByRef: (ref: string) => SchemaComponent;
668
  parseSchema: (
669
    rawSchema: string | RawTypeData,
670
    typeName?: string,
671
    formattersMap?: Record<MainSchemaTypes, (content: ModelType) => string>
672
  ) => ModelType;
673
  formatters: Record<MainSchemaTypes, (content: string | object | string[] | object[]) => string>;
674
  inlineExtraFormatters: Record<Exclude<MainSchemaTypes, SCHEMA_TYPES.PRIMITIVE>, (schema: ModelType) => string>;
675
  formatModelName: (name: string) => string;
676
  fmtToJSDocLine: (line: string, params?: { eol?: boolean }) => string;
677
  _: import("lodash").LoDashStatic;
678
  require: (path: string) => unknown;
679
}
680
```
681

682
### Schema Types Enum
683

684
```typescript { .api }
685
enum SCHEMA_TYPES {
686
  ARRAY = "array",
687
  OBJECT = "object",
688
  ENUM = "enum",
689
  REF = "$ref",
690
  PRIMITIVE = "primitive",
691
  COMPLEX = "complex",
692
  COMPLEX_ONE_OF = "oneOf",
693
  COMPLEX_ANY_OF = "anyOf",
694
  COMPLEX_ALL_OF = "allOf",
695
  COMPLEX_NOT = "not",
696
  COMPLEX_UNKNOWN = "__unknown"
697
}
698

699
type MainSchemaTypes = 
700
  | SCHEMA_TYPES.PRIMITIVE
701
  | SCHEMA_TYPES.OBJECT
702
  | SCHEMA_TYPES.ENUM;
703
```
704

705
### Internal Configuration Types
706

707
```typescript { .api }
708
interface TemplatePaths {
709
  base: string;
710
  default: string;
711
  modular: string;
712
  original: string;
713
  custom: string | null;
714
}
715

716
interface TemplatesToRender {
717
  api: string;
718
  dataContracts: string;
719
  httpClient: string;
720
  routeTypes: string;
721
  routeName: string;
722
  dataContractJsDoc: string;
723
  interfaceDataContract: string;
724
  typeDataContract: string;
725
  enumDataContract: string;
726
  objectFieldJsDoc: string;
727
}
728

729
interface FileNames {
730
  dataContracts: string;
731
  routeTypes: string;
732
  httpClient: string;
733
  outOfModuleApi: string;
734
}
735

736
interface InternalTemplateOptions {
737
  addUtilRequiredKeysType: boolean;
738
}
739
```