Skip to content

Commit 4bdaef3

Browse files
octogonzoctogonz
committed
Created api-extractor-template.json illustrating the redesigned config file schema
1 parent 9f41072 commit 4bdaef3

1 file changed

Lines changed: 290 additions & 0 deletions

File tree

‎apps/api-extractor/src/schemas/api-extractor-template.json‎

Lines changed: 290 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,290 @@
1+
{
2+
"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
3+
4+
/**
5+
* Optionally specifies another JSON config file that this file extends from. This provides a way for
6+
* standard settings to be shared across multiple projects.
7+
*
8+
* The path is resolved relative to the folder of the file with the "extends" field.
9+
*
10+
* DEFAULT VALUE: ""
11+
*/
12+
// "extends": "./node_modules/your-tool-chain/include/api-extractor-base.json"
13+
14+
/**
15+
* (REQUIRED) Settings that configure the TypeScript compiler engine used by API Extractor to perform the analysis.
16+
*/
17+
"compiler": {
18+
/**
19+
* (REQUIRED) For a JSON configuration file file, this value is always "tsconfig". (When invoking the
20+
* API Extractor engine programmatically, you can instead specify "runtime" to provide an already prepared
21+
* compiler state.)
22+
*/
23+
"configType": "tsconfig",
24+
25+
/**
26+
* The root folder for the project. This folder typically contains the tsconfig.json and package.json
27+
* config files.
28+
*
29+
* The "rootFolder" path is resolved relative to the folder containing api-extractor.json.
30+
*
31+
* The default value for "rootFolder" is the token "<lookup>", which means the folder is determined by traversing
32+
* parent folders, starting from the folder containing api-extractor.json, and stopping at the first folder
33+
* that contains a tsconfig.json file. If a tsconfig.json file cannot be found in this way, then an error
34+
* will be reported.
35+
*
36+
* DEFAULT VALUE: "<lookup>"
37+
*/
38+
// "rootFolder": "",
39+
40+
/**
41+
* This option causes the typechecker to be invoked with the --skipLibCheck option. This option is not recommended
42+
* and may cause API Extractor to produce incomplete or incorrect declarations, but it may be required when
43+
* dependencies contain declarations that are incompatible with the TypeScript engine that API Extractor uses
44+
* for its analysis. Where possible, broken dependencies should be fixed rather than relying on skipLibCheck.
45+
*
46+
* DEFAULT VALUE: false
47+
*/
48+
// "skipLibCheck": true,
49+
},
50+
51+
/**
52+
* (REQUIRED) Specifies the .d.ts file to be used as the starting point for analysis. API Extractor
53+
* analyzes the symbols exported by this module.
54+
*
55+
* The path is resolved relative to the "rootFolder" location.
56+
*/
57+
// "mainEntryPointFile": "./lib/index.d.ts"
58+
59+
/**
60+
* Configures how the API report file (*.api.md) will be generated.
61+
*/
62+
"apiReport": {
63+
/**
64+
* Whether to generate an API report.
65+
*
66+
* DEFAULT VALUE: true
67+
*/
68+
"enabled": true,
69+
70+
/**
71+
* The filename for the API report files. It will be combined with "trackedFolder" or "tempFolder" to produce
72+
* a full output filename.
73+
*
74+
* The file extension should be ".api.md", and the string should not contain a path separator such as "\" or "/".
75+
*
76+
* DEFAULT VALUE: "<packageBaseName>.api.md"
77+
*/
78+
// "reportFileName": "<packageBaseName>.api.md",
79+
80+
/**
81+
* Specifies the folder where the API report file is written. The file name portion is determined by
82+
* the "reportFileName" setting.
83+
*
84+
* The API report file is normally tracked by Git. Changes to it can be used to trigger a branch policy,
85+
* e.g. for an API review.
86+
*
87+
* The path is resolved relative to the "rootFolder" location.
88+
*
89+
* DEFAULT VALUE: "./etc"
90+
*/
91+
// "reportFolder": "./etc",
92+
93+
/**
94+
* Specifies the folder where the temporary report file is written. The file name portion is determined by
95+
* the "reportFileName" setting.
96+
*
97+
* After the temporary file is written to disk, it is compared with the file in the "reportFolder".
98+
* If they are different, a production build will fail.
99+
*
100+
* The path is resolved relative to the "rootFolder" location.
101+
*
102+
* DEFAULT VALUE: "./temp"
103+
*/
104+
// "tempFolder": "./temp"
105+
},
106+
107+
/**
108+
* Configures how the doc model file (*.api.json) will be generated.
109+
*/
110+
"docModel": {
111+
/**
112+
* Whether to generate doc model file.
113+
*
114+
* DEFAULT VALUE: true
115+
*/
116+
"enabled": true,
117+
118+
/**
119+
* The output path for the doc model file. The file extension should be ".api.json".
120+
*
121+
* The path is resolved relative to the "rootFolder" location.
122+
*
123+
* DEFAULT VALUE: "./temp/<packageBaseName>.api.json"
124+
*/
125+
"apiJsonFilePath": "./temp/<packageBaseName>.api.json"
126+
},
127+
128+
/**
129+
* Configures how the .d.ts rollup file will be generated.
130+
*/
131+
"dtsRollup": {
132+
/**
133+
* Whether to generate the .d.ts rollup file.
134+
*
135+
* DEFAULT VALUE: true
136+
*/
137+
"enabled": true,
138+
139+
/**
140+
* Specifies the output path for a .d.ts rollup file to be generated without any trimming.
141+
* This file will include all declarations that are exported by the main entry point.
142+
*
143+
* If the path is an empty string, then this file will not be written.
144+
*
145+
* The path is resolved relative to the "rootFolder" location.
146+
*
147+
* DEFAULT VALUE: "./dist/<packageBaseName>.d.ts"
148+
*/
149+
"untrimmedFilePath": "./dist/<packageBaseName>.d.ts",
150+
151+
/**
152+
* Specifies the output path for a .d.ts rollup file to be generated with trimming for a "beta" release.
153+
* This file will include only declarations that are marked as "@public" or "@beta".
154+
*
155+
* If the path is an empty string, then this file will not be written.
156+
*
157+
* The path is resolved relative to the "rootFolder" location.
158+
*
159+
* DEFAULT VALUE: ""
160+
*/
161+
// "betaTrimmedFilePath": "./dist/<packageBaseName>-beta.d.ts",
162+
163+
164+
/**
165+
* Specifies the output path for a .d.ts rollup file to be generated with trimming for a "public" release.
166+
* This file will include only declarations that are marked as "@public".
167+
*
168+
* If the path is an empty string, then this file will not be written.
169+
*
170+
* The path is resolved relative to the "rootFolder" location.
171+
*
172+
* DEFAULT VALUE: ""
173+
*/
174+
// "publicTrimmedFilePath": "./dist/<packageBaseName>-public.d.ts",
175+
},
176+
177+
/**
178+
* Configures how the tsdoc-metadata.json file will be generated.
179+
*/
180+
"tsdocMetadata": {
181+
/**
182+
* Whether to generate the tsdoc-metadata.json file.
183+
*
184+
* DEFAULT VALUE: true
185+
*/
186+
"enabled": true,
187+
188+
/**
189+
* Specifies where the TSDoc metadata file should be written.
190+
*
191+
* The default value is "<lookup>", which causes the path to be automatically inferred from the "tsdocMetadata",
192+
* "typings" or "main" fields of the project's package.json. If none of these fields are set, the lookup
193+
* falls back to "./tsdoc-metadata.json".
194+
*
195+
* DEFAULT VALUE: "<lookup>"
196+
*/
197+
// "tsdocMetadataFilePath": "./dist/tsdoc-metadata.json"
198+
},
199+
200+
/**
201+
* Configures how API Extractor reports error and warning messages produced during analysis.
202+
*
203+
* There are three sources of messages: compiler messages, API Extractor messages, and TSDoc messages.
204+
*/
205+
"messages": {
206+
/**
207+
* Configures handling of diagnostic messages reported by the TypeScript compiler engine while analyzing
208+
* the input .d.ts files.
209+
*
210+
* TypeScript message identifiers start with "TS" followed by an integer. For example: "TS2551"
211+
*
212+
* DEFAULT VALUE: A single "default" entry with logLevel=warning.
213+
*/
214+
"compilerMessageReporting": {
215+
/**
216+
* Configures the default routing for messages that don't match an explicit rule in this table.
217+
*/
218+
"default": {
219+
/**
220+
* Specifies whether the message should be written to the the tool's output log. Note that
221+
* the "addToApiReviewFile" property may supersede this option.
222+
*
223+
* Possible values: "error", "warning", "none"
224+
*
225+
* DEFAULT VALUE: "warning"
226+
*/
227+
// "logLevel": "warning",
228+
229+
/**
230+
* When addToApiReviewFile is true: If API Extractor is configured to write an API report file (.api.md),
231+
* then the message will be written inside that file; otherwise, the message is instead logged according to
232+
* the "logLevel" option.
233+
*
234+
* DEFAULT VALUE: false
235+
*/
236+
// "addToApiReviewFile": false
237+
},
238+
239+
// "TS2551": {
240+
// "logLevel": "warning",
241+
// "addToApiReviewFile": true
242+
// },
243+
//
244+
// . . .
245+
},
246+
247+
/**
248+
* Configures handling of diagnostic messages reported by API Extractor during its analysis.
249+
*
250+
* API Extractor message identifiers start with "ae-". For example: "ae-extra-release-tag"
251+
*
252+
* DEFAULT VALUE: See api-extractor-defaults.json for the complete table of extractorMessageReporting mappings
253+
*/
254+
"extractorMessageReporting": {
255+
"default": {
256+
// "logLevel": "warning",
257+
// "addToApiReviewFile": false
258+
},
259+
260+
// "ae-extra-release-tag": {
261+
// "logLevel": "warning",
262+
// "addToApiReviewFile": true
263+
// },
264+
//
265+
// . . .
266+
},
267+
268+
/**
269+
* Configures handling of messages reported by the TSDoc parser when analyzing code comments.
270+
*
271+
* TSDoc message identifiers start with "tsdoc-". For example: "tsdoc-link-tag-unescaped-text"
272+
*
273+
* DEFAULT VALUE: A single "default" entry with logLevel=warning.
274+
*/
275+
"tsdocMessageReporting": {
276+
"default": {
277+
// "logLevel": "warning",
278+
// "addToApiReviewFile": false
279+
}
280+
281+
// "tsdoc-link-tag-unescaped-text": {
282+
// "logLevel": "warning",
283+
// "addToApiReviewFile": true
284+
// },
285+
//
286+
// . . .
287+
}
288+
}
289+
290+
}

0 commit comments

Comments
 (0)