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
```