0
# AutoRest Core
1

2
AutoRest Core is the core module of the AutoRest toolchain that generates client libraries for accessing RESTful web services from OpenAPI (formerly Swagger) specifications. It provides a comprehensive TypeScript API for programmatic code generation, configuration management, file system abstraction, and document processing capabilities essential for automating SDK creation across multiple target languages and platforms.
3

4
## Package Information
5

6
- **Package Name**: @microsoft.azure/autorest-core
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @microsoft.azure/autorest-core`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  AutoRest, 
16
  ConfigurationView, 
17
  IFileSystem, 
18
  Message, 
19
  Channel, 
20
  Artifact 
21
} from "@microsoft.azure/autorest-core";
22
```
23

24
For CommonJS:
25

26
```javascript
27
const { 
28
  AutoRest, 
29
  ConfigurationView, 
30
  IFileSystem, 
31
  Message, 
32
  Channel, 
33
  Artifact 
34
} = require("@microsoft.azure/autorest-core");
35
```
36

37
## Basic Usage
38

39
```typescript
40
import { AutoRest } from "@microsoft.azure/autorest-core";
41

42
// Create AutoRest instance (uses default file system)
43
const autorest = new AutoRest();
44

45
// Add configuration
46
autorest.AddConfiguration({
47
  "input-file": "swagger.json",
48
  "output-folder": "./generated",
49
  "client-name": "MyApiClient"
50
});
51

52
// Set up event handlers
53
autorest.Message.Subscribe((_, message) => {
54
  console.log(`[${message.Channel}] ${message.Text}`);
55
});
56

57
autorest.GeneratedFile.Subscribe((_, artifact) => {
58
  console.log(`Generated: ${artifact.uri}`);
59
});
60

61
// Process and generate code
62
const result = await autorest.Process().finish;
63
if (result === true) {
64
  console.log("Code generation completed successfully");
65
} else {
66
  console.error("Code generation failed:", result);
67
}
68
```
69

70
## Architecture
71

72
AutoRest Core is built around several key components:
73

74
- **Processing Engine**: `AutoRest` class orchestrates the entire code generation pipeline
75
- **Configuration System**: Hierarchical configuration merging with literate configuration support
76
- **File System Abstraction**: Pluggable file system interfaces for various environments
77
- **Message System**: Event-driven communication with structured logging and progress reporting
78
- **Document Processing**: OpenAPI specification parsing, validation, and transformation utilities
79
- **Plugin Architecture**: Extensible pipeline for integrating custom transformations and generators
80

81
## Capabilities
82

83
### AutoRest Processing
84

85
Core code generation orchestration using the AutoRest class. Manages the entire pipeline from specification loading to code generation with comprehensive event handling and configuration management.
86

87
```typescript { .api }
88
class AutoRest extends EventEmitter {
89
  constructor(fileSystem?: IFileSystem, configFileOrFolderUri?: string);
90
  AddConfiguration(configuration: any): void;
91
  Process(): { finish: Promise<boolean | Error>, cancel: () => void };
92
  get view(): Promise<ConfigurationView>;
93
}
94
```
95

96
[AutoRest Processing](./autorest-processing.md)
97

98
### File System Operations
99

100
File system abstraction interface for AutoRest operations.
101

102
```typescript { .api }
103
interface IFileSystem {
104
  EnumerateFileUris(folderUri: string): Promise<Array<string>>;
105
  ReadFile(uri: string): Promise<string>;
106
}
107
```
108

109
### Configuration Management
110

111
Hierarchical configuration system with support for literate configuration documents, command-line overrides, and extensible validation.
112

113
```typescript { .api }
114
interface ConfigurationView {
115
  Keys: Array<string>;
116
  UseExtensions: Array<{ name: string, source: string, fullyQualified: string }>;
117
  Directives: DirectiveView[];
118
  InputFileUris: Array<string>;
119
  OutputFolderUri: string;
120
  Raw: any;
121
  DebugMode: boolean;
122
  VerboseMode: boolean;
123
  HelpRequested: boolean;
124
  GetEntry(key: string): any;
125
  Dump(title?: string): void;
126
  IncludedConfigurationFiles(fileSystem: IFileSystem, ignoreFiles: Set<string>): Promise<string[]>;
127
  IsOutputArtifactRequested(artifact: string): boolean;
128
  GetNestedConfiguration(pluginName: string): Iterable<ConfigurationView>;
129
  GetNestedConfigurationImmediate(...scope: any[]): ConfigurationView;
130
  Message(m: Message): void;
131
  messageEmitter: MessageEmitter;
132
  CancellationToken: CancellationToken;
133
}
134

135
interface AutoRestConfigurationImpl {
136
  "input-file"?: string[] | string;
137
  "output-folder"?: string;
138
  "base-folder"?: string;
139
  "debug"?: boolean;
140
  "verbose"?: boolean;
141
}
142
```
143

144
[Configuration](./configuration.md)
145

146
### Message Handling
147

148
Comprehensive message and event system for progress reporting, error handling, and structured logging throughout the generation process.
149

150
```typescript { .api }
151
interface Message {
152
  Channel: Channel;
153
  Text: string;
154
  Key?: Iterable<string>;
155
  Details?: any;
156
  Source?: Array<SourceLocation>;
157
}
158

159
enum Channel {
160
  Information = "information",
161
  Warning = "warning", 
162
  Error = "error",
163
  Debug = "debug",
164
  Verbose = "verbose",
165
  Fatal = "fatal",
166
  Hint = "hint",
167
  File = "file",
168
  Configuration = "configuration"
169
}
170
```
171

172
[Message Handling](./message-handling.md)
173

174
### Document Processing
175

176
Utilities for processing OpenAPI specifications, literate configuration documents, and various input formats with automatic type detection and conversion.
177

178
```typescript { .api }
179
function IdentifyDocument(content: string): Promise<DocumentType>;
180
function LiterateToJson(content: string): Promise<string>;
181
function IsOpenApiDocument(content: string): Promise<boolean>;
182
function IsConfigurationDocument(content: string): Promise<boolean>;
183
function Shutdown(): Promise<void>;
184

185
enum DocumentType {
186
  OpenAPI2 = "OpenAPI2",
187
  OpenAPI3 = "OpenAPI3", 
188
  LiterateConfiguration = "LiterateConfiguration",
189
  Unknown = "Unknown"
190
}
191
```
192

193
[Document Processing](./document-processing.md)
194

195
## Types
196

197
### Core Interfaces
198

199
```typescript { .api }
200
interface Artifact {
201
  uri: string;
202
  type: string;
203
  content: string;
204
}
205

206
interface SourceLocation {
207
  document: string;
208
  Position: EnhancedPosition;
209
}
210

211
interface Range {
212
  document: string;
213
  start: Position;
214
  end: Position;
215
}
216

217
interface Position {
218
  line: number;
219
  column: number;
220
}
221

222
interface EnhancedPosition extends Position {
223
  [key: string]: any;
224
}
225

226
interface DirectiveView {
227
  where?: string;
228
  reason?: string;
229
  from?: string;
230
  transform?: string;
231
  set?: { [key: string]: any };
232
  remove?: boolean;
233
  rename?: { [oldName: string]: string };
234
}
235
```
236

237
### System Interfaces
238

239
```typescript { .api }
240
interface MessageEmitter {
241
  Message: IEvent<any, Message>;
242
}
243

244
interface CancellationToken {
245
  isCancellationRequested: boolean;
246
  onCancellationRequested: IEvent<CancellationToken, any>;
247
}
248

249
interface CancellationTokenSource {
250
  token: CancellationToken;
251
  cancel(): void;
252
}
253

254
interface IEvent<TSource, TArgs> {
255
  Subscribe(fn: (source: TSource, args: TArgs) => void): void;
256
  Dispatch(args: TArgs): void;
257
}
258
```
259

260
### Document Classification
261

262
```typescript { .api }
263
enum DocumentFormat {
264
  Markdown = "markdown",
265
  Yaml = "yaml",
266
  Json = "json",
267
  Unknown = "unknown"
268
}
269

270
const DocumentExtension: {
271
  yaml: DocumentFormat.Yaml;
272
  yml: DocumentFormat.Yaml;
273
  json: DocumentFormat.Json;
274
  md: DocumentFormat.Markdown;
275
  markdown: DocumentFormat.Markdown;
276
};
277

278
const DocumentPatterns: {
279
  yaml: string[];
280
  json: string[];
281
  markdown: string[];
282
  all: string[];
283
};
284
```