0
# AutoRest Core
1
2
AutoRest Core is the foundational module of the AutoRest code generation tool, which generates client libraries for accessing RESTful web services from OpenAPI specifications. This package provides the core functionality for parsing, validating, and transforming OpenAPI specs into code generation artifacts, serving as the central processing engine that coordinates with language-specific generators.
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
IdentifyDocument,
22
LiterateToJson,
23
IsConfigurationDocument,
24
IsOpenApiDocument,
25
IsConfigurationExtension,
26
IsOpenApiExtension,
27
DocumentType,
28
DocumentFormat,
29
DocumentExtension,
30
DocumentPatterns
31
} from "@microsoft.azure/autorest-core";
32
33
// File system implementations (not re-exported from main, import directly)
34
import { RealFileSystem, MemoryFileSystem, EnhancedFileSystem } from "@microsoft.azure/autorest-core/lib/file-system";
35
```
36
37
For CommonJS:
38
39
```javascript
40
const {
41
AutoRest,
42
ConfigurationView,
43
IFileSystem,
44
Message,
45
Channel,
46
Artifact
47
} = require("@microsoft.azure/autorest-core");
48
```
49
50
## Basic Usage
51
52
```typescript
53
import { AutoRest } from "@microsoft.azure/autorest-core";
54
import { RealFileSystem } from "@microsoft.azure/autorest-core/lib/file-system";
55
56
// Create AutoRest instance with file system
57
const autorest = new AutoRest(new RealFileSystem(), "./autorest-config.json");
58
59
// Add configuration
60
autorest.AddConfiguration({
61
"input-file": "swagger.json",
62
"output-folder": "./generated",
63
"namespace": "MyClient"
64
});
65
66
// Listen to events
67
const unsubscribeGenerated = autorest.GeneratedFile.Subscribe((autorest, artifact) => {
68
console.log(`Generated: ${artifact.uri}`);
69
});
70
71
const unsubscribeMessage = autorest.Message.Subscribe((autorest, message) => {
72
console.log(`${message.Channel}: ${message.Text}`);
73
});
74
75
// Start processing
76
const { finish, cancel } = autorest.Process();
77
const result = await finish;
78
```
79
80
## Architecture
81
82
AutoRest Core is built around several key components:
83
84
- **AutoRest Class**: Main generator instance that orchestrates the entire process
85
- **File System Abstraction**: Pluggable file system implementations (Real, Memory, Enhanced)
86
- **Configuration System**: Hierarchical configuration loading and management
87
- **Message System**: Event-driven communication with detailed logging and error reporting
88
- **Pipeline System**: Extensible processing pipeline with plugin support
89
- **Document Processing**: OpenAPI and configuration document identification and parsing
90
- **Type System**: Complete TypeScript integration with full type definitions
91
92
## Capabilities
93
94
### AutoRest Generator
95
96
Main generator class that coordinates the entire code generation process with event-driven architecture and configuration management.
97
98
```typescript { .api }
99
class AutoRest {
100
constructor(fileSystem?: IFileSystem, configFileOrFolderUri?: string);
101
view: Promise<ConfigurationView>;
102
AddConfiguration(configuration: any): void;
103
ResetConfiguration(): Promise<void>;
104
Process(): { finish: Promise<boolean | Error>, cancel: () => void };
105
106
// Events
107
Finished: IEvent<AutoRest, boolean | Error>;
108
GeneratedFile: IEvent<AutoRest, Artifact>;
109
ClearFolder: IEvent<AutoRest, string>;
110
Message: IEvent<AutoRest, Message>;
111
}
112
```
113
114
[AutoRest Generator](./autorest-generator.md)
115
116
### File System Operations
117
118
File system abstraction providing pluggable implementations for different environments, including real file system, in-memory operations, and GitHub integration.
119
120
```typescript { .api }
121
interface IFileSystem {
122
EnumerateFileUris(folderUri: string): Promise<Array<string>>;
123
ReadFile(uri: string): Promise<string>;
124
}
125
126
class RealFileSystem implements IFileSystem {
127
constructor();
128
EnumerateFileUris(folderUri: string): Promise<string[]>;
129
ReadFile(uri: string): Promise<string>;
130
WriteFile(uri: string, content: string): Promise<void>;
131
}
132
133
class MemoryFileSystem implements IFileSystem {
134
constructor(files: Map<string, string>);
135
readonly Outputs: Map<string, string>;
136
ReadFile(uri: string): Promise<string>;
137
EnumerateFileUris(folderUri?: string): Promise<Array<string>>;
138
WriteFile(uri: string, content: string): Promise<void>;
139
}
140
141
class EnhancedFileSystem implements IFileSystem {
142
constructor(githubAuthToken?: string);
143
EnumerateFileUris(folderUri: string): Promise<string[]>;
144
ReadFile(uri: string): Promise<string>;
145
WriteFile(uri: string, content: string): Promise<void>;
146
}
147
```
148
149
[File System Operations](./file-system.md)
150
151
### Document Processing
152
153
Document type identification and format detection for OpenAPI specifications and configuration files.
154
155
```typescript { .api }
156
function IdentifyDocument(content: string): Promise<DocumentType>;
157
function LiterateToJson(content: string): Promise<string>;
158
function IsConfigurationDocument(content: string): Promise<boolean>;
159
function IsOpenApiDocument(content: string): Promise<boolean>;
160
function IsConfigurationExtension(extension: string): Promise<boolean>;
161
function IsOpenApiExtension(extension: string): Promise<boolean>;
162
163
enum DocumentType {
164
OpenAPI2 = "OpenAPI2",
165
OpenAPI3 = "OpenAPI3",
166
LiterateConfiguration = "LiterateConfiguration",
167
Unknown = "Unknown"
168
}
169
170
enum DocumentFormat {
171
Markdown = "markdown",
172
Yaml = "yaml",
173
Json = "json",
174
Unknown = "unknown"
175
}
176
177
const DocumentExtension: {
178
yaml: DocumentFormat.Yaml;
179
yml: DocumentFormat.Yaml;
180
json: DocumentFormat.Json;
181
md: DocumentFormat.Markdown;
182
markdown: DocumentFormat.Markdown;
183
};
184
185
const DocumentPatterns: {
186
yaml: string[];
187
json: string[];
188
markdown: string[];
189
all: string[];
190
};
191
```
192
193
[Document Processing](./document-processing.md)
194
195
### Configuration Management
196
197
Hierarchical configuration system with support for multiple configuration sources and view-based access patterns.
198
199
```typescript { .api }
200
class ConfigurationView {
201
// Configuration access and management methods
202
}
203
204
interface AutoRestConfigurationImpl {
205
// Core processing options
206
"input-file"?: string | string[];
207
"output-folder"?: string;
208
"base-folder"?: string;
209
210
// Processing flags
211
"debug"?: boolean;
212
"verbose"?: boolean;
213
"message-format"?: string;
214
215
// Plugin options
216
"use-extension"?: string | string[];
217
"require"?: string | string[];
218
"directive"?: any[];
219
220
// Language-specific options
221
"namespace"?: string;
222
"package-name"?: string;
223
}
224
```
225
226
[Configuration Management](./configuration.md)
227
228
### Message System
229
230
Event-driven messaging system with structured logging, error reporting, and multi-channel communication.
231
232
```typescript { .api }
233
interface Message {
234
Channel: Channel;
235
Key?: Iterable<string>;
236
Details?: any;
237
Text: string;
238
Source?: Array<SourceLocation>;
239
Range?: Iterable<Range>;
240
Plugin?: string;
241
FormattedMessage?: string;
242
}
243
244
enum Channel {
245
Information = "information",
246
Warning = "warning",
247
Error = "error",
248
Debug = "debug",
249
Verbose = "verbose",
250
Fatal = "fatal",
251
Hint = "hint",
252
File = "file",
253
Configuration = "configuration"
254
}
255
256
interface Artifact {
257
uri: string;
258
type: string;
259
content: string;
260
}
261
```
262
263
[Message System](./messaging.md)
264
265
## Binary Entry Points
266
267
The package provides two CLI tools:
268
269
- **autorest-core**: Main CLI for processing OpenAPI specifications (`dist/app.js`)
270
- **autorest-language-service**: Language service for editor integration (`dist/language-service/language-service.js`)
271
272
273
## Types
274
275
```typescript { .api }
276
interface SourceLocation {
277
document: string;
278
Position: EnhancedPosition;
279
}
280
281
interface Range {
282
document: string;
283
start: Position;
284
end: Position;
285
}
286
287
interface Position {
288
line: number;
289
column: number;
290
}
291
292
interface IEvent<TSender, TArgs> {
293
Subscribe(fn: (sender: TSender, args: TArgs) => void): () => void;
294
Unsubscribe(fn: (sender: TSender, args: TArgs) => void): void;
295
Dispatch(args: TArgs): void;
296
}
297
```