Skip to content

Commit 59dc879

Browse files
hkleungaihkleungai
authored
🤖 Merge PR DefinitelyTyped#74611 feat(swagger-ui): update SwaggerUIOptions, exports config & plugins by @hkleungai 
1 parent 925f66c commit 59dc879

File tree

3 files changed

+252
-27
lines changed

3 files changed

+252
-27
lines changed

‎types/swagger-ui/index.d.ts‎

Lines changed: 80 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,10 @@ declare namespace SwaggerUI {
3737
name: string;
3838
}>
3939
| undefined;
40+
/**
41+
* Enables overriding configuration parameters via URL search params.
42+
*/
43+
queryConfigEnabled?: boolean | undefined;
4044

4145
// Plugin system
4246

@@ -45,10 +49,6 @@ declare namespace SwaggerUI {
4549
* for Swagger UI.
4650
*/
4751
layout?: string | undefined;
48-
/**
49-
* A Javascript object to configure plugin integration and behaviors
50-
*/
51-
pluginsOptions?: PluginsOptions;
5252
/**
5353
* An array of plugin functions to use in Swagger UI.
5454
*/
@@ -132,13 +132,6 @@ declare namespace SwaggerUI {
132132
* Default is the order determined by Swagger UI.
133133
*/
134134
tagsSorter?: SorterLike | undefined;
135-
/**
136-
* When enabled, sanitizer will leave style, class and data-* attributes untouched
137-
* on all HTML Elements declared inside markdown strings.
138-
* This parameter is Deprecated and will be removed in 4.0.0.
139-
* @deprecated
140-
*/
141-
useUnsafeMarkdown?: boolean | undefined;
142135
/**
143136
* Provides a mechanism to be notified when Swagger UI has finished rendering a newly provided definition.
144137
*/
@@ -164,6 +157,12 @@ declare namespace SwaggerUI {
164157
* Controls whether the "Try it out" section should be enabled by default.
165158
*/
166159
tryItOutEnabled?: boolean | undefined;
160+
/**
161+
* Enables the request snippet section.
162+
* When disabled, the legacy curl snippet will be used.
163+
* The default is false.
164+
*/
165+
requestSnippetsEnabled?: boolean | undefined;
167166
/**
168167
* This is the default configuration section for the the requestSnippets plugin.
169168
*/
@@ -249,6 +248,36 @@ declare namespace SwaggerUI {
249248
* If set to true, it persists authorization data and it would not be lost on browser close/refresh
250249
*/
251250
persistAuthorization?: boolean | undefined;
251+
252+
// Options missing from https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md
253+
254+
/**
255+
* Inline Plugin Option. See https://github.com/swagger-api/swagger-ui/blob/master/docs/customization/add-plugin.md
256+
*/
257+
components?: Indexable | undefined;
258+
/**
259+
* Inline Plugin Option. See https://github.com/swagger-api/swagger-ui/blob/master/docs/customization/add-plugin.md
260+
*/
261+
fn?: Indexable | undefined;
262+
/**
263+
* See https://github.com/swagger-api/swagger-ui/blob/master/src/core/config/factorization/system.js
264+
*/
265+
configs?: any;
266+
/**
267+
* Passes initial values to the Swagger UI state.
268+
* See https://github.com/swagger-api/swagger-ui/blob/master/src/core/config/factorization/system.js
269+
*/
270+
initialState?: any;
271+
/**
272+
* Used in src/core/plugins/oas3/fn.js
273+
*/
274+
fileUploadMediaTypes?: string[] | undefined;
275+
/**
276+
* Allows to define a custom uncaught exception handler.
277+
* The default is `null`, which means that the default handler will be used.
278+
* The default handler will log the error to the console.
279+
*/
280+
uncaughtExceptionHandler?: ((error: unknown) => unknown) | null | undefined;
252281
}
253282

254283
interface PluginsOptions {
@@ -313,14 +342,53 @@ declare namespace SwaggerUI {
313342
[index: string]: any;
314343
}
315344

345+
const config: {
346+
defaults: Required<SwaggerUIOptions>;
347+
merge: (target: SwaggerUIOptions, ...sources: SwaggerUIOptions[]) => SwaggerUIOptions;
348+
typeCast: (options: unknown) => SwaggerUIOptions;
349+
typeCastMappings: {
350+
[key in Exclude<keyof SwaggerUIOptions, "queryConfigEnabled">]-?: {
351+
typeCaster: (value: unknown, defaultValue?: SwaggerUIOptions[key]) => SwaggerUIOptions[key] | null;
352+
defaultValue?: SwaggerUIOptions[key];
353+
};
354+
};
355+
};
316356
/**
317357
* Internal presets
318358
* See https://swagger.io/docs/open-source-tools/swagger-ui/customization/overview/#presets
319359
*/
320-
var presets: {
360+
const presets: {
321361
base: SwaggerUIPreset;
322362
apis: SwaggerUIPreset;
323363
};
364+
365+
const plugins: {
366+
Auth: SwaggerUIPlugin;
367+
Configs: SwaggerUIPlugin;
368+
DeepLining: SwaggerUIPlugin;
369+
Err: SwaggerUIPlugin;
370+
Filter: SwaggerUIPlugin;
371+
Icons: SwaggerUIPlugin;
372+
JSONSchema5: SwaggerUIPlugin;
373+
JSONSchema5Samples: SwaggerUIPlugin;
374+
JSONSchema202012: SwaggerUIPlugin;
375+
JSONSchema202012Samples: SwaggerUIPlugin;
376+
Layout: SwaggerUIPlugin;
377+
Logs: SwaggerUIPlugin;
378+
OpenAPI30: SwaggerUIPlugin;
379+
OpenAPI31: SwaggerUIPlugin;
380+
OnComplete: SwaggerUIPlugin;
381+
RequestSnippets: SwaggerUIPlugin;
382+
Spec: SwaggerUIPlugin;
383+
SwaggerClient: SwaggerUIPlugin;
384+
Util: SwaggerUIPlugin;
385+
View: SwaggerUIPlugin;
386+
ViewLegacy: SwaggerUIPlugin;
387+
DownloadUrl: SwaggerUIPlugin;
388+
SyntaxHighlighting: SwaggerUIPlugin;
389+
Versions: SwaggerUIPlugin;
390+
SafeRender: SwaggerUIPlugin;
391+
};
324392
}
325393

326394
interface SwaggerUI {

‎types/swagger-ui/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"private": true,
33
"name": "@types/swagger-ui",
4-
"version": "5.21.9999",
4+
"version": "5.32.9999",
55
"projects": [
66
"https://github.com/swagger-api/swagger-ui"
77
],

‎types/swagger-ui/swagger-ui-tests.ts‎

Lines changed: 171 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,17 @@
11
import SwaggerUI = require("swagger-ui");
22

3-
SwaggerUI({
3+
declare let bool: boolean;
4+
5+
const swaggerUI = SwaggerUI({
46
configUrl: "http://www.example.com",
57
dom_id: "Some id",
68
domNode: document.getElementById("#eyedee"),
79
spec: {},
810
url: "http://www.example.com",
911
urls: [{ name: "123", url: "http://www.example.com" }],
12+
queryConfigEnabled: true,
1013

1114
layout: "Idontknow",
12-
pluginsOptions: {
13-
pluginLoadType: "legacy",
14-
},
1515
plugins: [
1616
() => {
1717
return {
@@ -40,13 +40,15 @@ SwaggerUI({
4040
showExtensions: false,
4141
showCommonExtensions: false,
4242
tagsSorter: (a: any) => a,
43-
useUnsafeMarkdown: false,
4443
onComplete: () => console.log("done"),
45-
syntaxHighlight: {
46-
activate: true,
47-
theme: "agate",
48-
},
44+
syntaxHighlight: bool
45+
? {
46+
activate: true,
47+
theme: "agate",
48+
}
49+
: false,
4950
tryItOutEnabled: false,
51+
requestSnippetsEnabled: true,
5052
requestSnippets: {
5153
generators: {
5254
curl_bash: {
@@ -78,16 +80,171 @@ SwaggerUI({
7880
parameterMacro: (op, param) => 0,
7981

8082
persistAuthorization: false,
81-
});
8283

83-
const swaggerUI = SwaggerUI({
84-
syntaxHighlight: false,
84+
components: {},
85+
fn: {},
86+
configs: {},
87+
initialState: {},
88+
fileUploadMediaTypes: [
89+
"application/octet-stream",
90+
"image/",
91+
"audio/",
92+
"video/",
93+
],
94+
uncaughtExceptionHandler: bool ? null : console.error,
8595
});
8696

97+
// $ExpectType Required<SwaggerUIOptions>
98+
SwaggerUI.config.defaults;
99+
// $ExpectType (target: SwaggerUIOptions, ...sources: SwaggerUIOptions[]) => SwaggerUIOptions
100+
SwaggerUI.config.merge;
101+
// (options: unknown) => SwaggerUIOptions
102+
SwaggerUI.config.typeCast;
103+
104+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: Indexable | undefined) => Indexable | null | undefined; defaultValue?: Indexable | undefined; }
105+
SwaggerUI.config.typeCastMappings.components;
106+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: string | undefined) => string | null | undefined; defaultValue?: string | undefined; }
107+
SwaggerUI.config.typeCastMappings.configUrl;
108+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: any) => any; defaultValue?: any; }
109+
SwaggerUI.config.typeCastMappings.configs;
110+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: boolean | undefined) => boolean | null | undefined; defaultValue?: boolean | undefined; }
111+
SwaggerUI.config.typeCastMappings.deepLinking;
112+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: number | undefined) => number | null | undefined; defaultValue?: number | undefined; }
113+
SwaggerUI.config.typeCastMappings.defaultModelExpandDepth;
114+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: "example" | "model" | undefined) => "example" | "model" | null | undefined; defaultValue?: "example" | "model" | undefined; }
115+
SwaggerUI.config.typeCastMappings.defaultModelRendering;
116+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: number | undefined) => number | null | undefined; defaultValue?: number | undefined; }
117+
SwaggerUI.config.typeCastMappings.defaultModelsExpandDepth;
118+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: boolean | undefined) => boolean | null | undefined; defaultValue?: boolean | undefined; }
119+
SwaggerUI.config.typeCastMappings.displayOperationId;
120+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: boolean | undefined) => boolean | null | undefined; defaultValue?: boolean | undefined; }
121+
SwaggerUI.config.typeCastMappings.displayRequestDuration;
122+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: "list" | "full" | "none" | undefined) => "list" | "full" | "none" | null | undefined; defaultValue?: "list" | "full" | "none" | undefined; }
123+
SwaggerUI.config.typeCastMappings.docExpansion;
124+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: HTMLElement | null | undefined) => HTMLElement | null | undefined; defaultValue?: HTMLElement | null | undefined; }
125+
SwaggerUI.config.typeCastMappings.domNode;
126+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: string | undefined) => string | null | undefined; defaultValue?: string | undefined; }
127+
SwaggerUI.config.typeCastMappings.dom_id;
128+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: string[] | undefined) => string[] | null | undefined; defaultValue?: string[] | undefined; }
129+
SwaggerUI.config.typeCastMappings.fileUploadMediaTypes;
130+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: string | boolean | undefined) => string | boolean | null | undefined; defaultValue?: string | boolean | undefined; }
131+
SwaggerUI.config.typeCastMappings.filter;
132+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: Indexable | undefined) => Indexable | null | undefined; defaultValue?: Indexable | undefined; }
133+
SwaggerUI.config.typeCastMappings.fn;
134+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: any) => any; defaultValue?: any; }
135+
SwaggerUI.config.typeCastMappings.initialState;
136+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: string | undefined) => string | null | undefined; defaultValue?: string | undefined; }
137+
SwaggerUI.config.typeCastMappings.layout;
138+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: number | undefined) => number | null | undefined; defaultValue?: number | undefined; }
139+
SwaggerUI.config.typeCastMappings.maxDisplayedTags;
140+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: ((propName: Readonly<any>) => any) | undefined) => ((propName: Readonly<any>) => any) | null | undefined; defaultValue?: ((propName: Readonly<any>) => any) | undefined; }
141+
SwaggerUI.config.typeCastMappings.modelPropertyMacro;
142+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: string | undefined) => string | null | undefined; defaultValue?: string | undefined; }
143+
SwaggerUI.config.typeCastMappings.oauth2RedirectUrl;
144+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: (() => any) | undefined) => (() => any) | null | undefined; defaultValue?: (() => any) | undefined; }
145+
SwaggerUI.config.typeCastMappings.onComplete;
146+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: SorterLike | undefined) => SorterLike | null | undefined; defaultValue?: SorterLike | undefined; }
147+
SwaggerUI.config.typeCastMappings.operationsSorter;
148+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: ((operation: Readonly<any>, parameter: Readonly<any>) => any) | undefined) => ((operation: Readonly<any>, parameter: Readonly<any>) => any) | null | undefined; defaultValue?: ((operation: Readonly<any>, parameter: Readonly<any>) => any) | undefined; }
149+
SwaggerUI.config.typeCastMappings.parameterMacro;
150+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: boolean | undefined) => boolean | null | undefined; defaultValue?: boolean | undefined; }
151+
SwaggerUI.config.typeCastMappings.persistAuthorization;
152+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: SwaggerUIPlugin[] | undefined) => SwaggerUIPlugin[] | null | undefined; defaultValue?: SwaggerUIPlugin[] | undefined; }
153+
SwaggerUI.config.typeCastMappings.plugins;
154+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: SwaggerUIPlugin[] | SwaggerUIPreset[] | undefined) => SwaggerUIPlugin[] | SwaggerUIPreset[] | null | undefined; defaultValue?: SwaggerUIPlugin[] | SwaggerUIPreset[] | undefined; }
155+
SwaggerUI.config.typeCastMappings.presets;
156+
// @ts-expect-error
157+
SwaggerUI.config.typeCastMappings.queryConfigEnabled;
158+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: ((a: Request) => Request | Promise<Request>) | undefined) => ((a: Request) => Request | Promise<Request>) | null | undefined; defaultValue?: ((a: Request) => Request | Promise<Request>) | undefined; }
159+
SwaggerUI.config.typeCastMappings.requestInterceptor;
160+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: { generators?: { [genName: string]: { title: string; syntax: string; }; } | undefined; defaultExpanded?: boolean | undefined; languagesMask?: string[] | undefined; } | undefined) => { generators?: { [genName: string]: { title: string; syntax: string; }; } | undefined; defaultExpanded?: boolean | undefined; languagesMask?: string[] | undefined; } | null | undefined; defaultValue?: { generators?: { [genName: string]: { title: string; syntax: string; }; } | undefined; defaultExpanded?: boolean | undefined; languagesMask?: string[] | undefined; } | undefined; }
161+
SwaggerUI.config.typeCastMappings.requestSnippets;
162+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: boolean | undefined) => boolean | null | undefined; defaultValue?: boolean | undefined; }
163+
SwaggerUI.config.typeCastMappings.requestSnippetsEnabled;
164+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: ((a: Response) => Response | Promise<Response>) | undefined) => ((a: Response) => Response | Promise<Response>) | null | undefined; defaultValue?: ((a: Response) => Response | Promise<Response>) | undefined; }
165+
SwaggerUI.config.typeCastMappings.responseInterceptor;
166+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: boolean | undefined) => boolean | null | undefined; defaultValue?: boolean | undefined; }
167+
SwaggerUI.config.typeCastMappings.showCommonExtensions;
168+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: boolean | undefined) => boolean | null | undefined; defaultValue?: boolean | undefined; }
169+
SwaggerUI.config.typeCastMappings.showExtensions;
170+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: boolean | undefined) => boolean | null | undefined; defaultValue?: boolean | undefined; }
171+
SwaggerUI.config.typeCastMappings.showMutatedRequest;
172+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: { [propName: string]: any } | undefined) => { [propName: string]: any } | null | undefined; defaultValue?: { [propName: string]: any } | undefined; }
173+
SwaggerUI.config.typeCastMappings.spec;
174+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: SupportedHTTPMethods[] | undefined) => SupportedHTTPMethods[] | null | undefined; defaultValue?: SupportedHTTPMethods[] | undefined; }
175+
SwaggerUI.config.typeCastMappings.supportedSubmitMethods;
176+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: false | { activate?: boolean | undefined; theme?: "agate" | "arta" | "idea" | "monokai" | "nord" | "obsidian" | "tomorrow-night" | undefined; } | undefined) => false | { activate?: boolean | undefined; theme?: "agate" | "arta" | "idea" | "monokai" | "nord" | "obsidian" | "tomorrow-night" | undefined; } | null | undefined; defaultValue?: false | { activate?: boolean | undefined; theme?: "agate" | "arta" | "idea" | "monokai" | "nord" | "obsidian" | "tomorrow-night" | undefined; } | undefined; }
177+
SwaggerUI.config.typeCastMappings.syntaxHighlight;
178+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: SorterLike | undefined) => SorterLike | null | undefined; defaultValue?: SorterLike | undefined; }
179+
SwaggerUI.config.typeCastMappings.tagsSorter;
180+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: boolean | undefined) => boolean | null | undefined; defaultValue?: boolean | undefined; }
181+
SwaggerUI.config.typeCastMappings.tryItOutEnabled;
182+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: ((error: unknown) => unknown) | null | undefined) => ((error: unknown) => unknown) | null | undefined; defaultValue?: ((error: unknown) => unknown) | null | undefined; }
183+
SwaggerUI.config.typeCastMappings.uncaughtExceptionHandler;
184+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: string | undefined) => string | null | undefined; defaultValue?: string | undefined; }
185+
SwaggerUI.config.typeCastMappings.url;
186+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: { url: string; name: string; }[] | undefined) => { url: string; name: string; }[] | null | undefined; defaultValue?: { url: string; name: string; }[] | undefined; }
187+
SwaggerUI.config.typeCastMappings.urls;
188+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: string | undefined) => string | null | undefined; defaultValue?: string | undefined; }
189+
SwaggerUI.config.typeCastMappings.validatorUrl;
190+
// $ExpectType { typeCaster: (value: unknown, defaultValue?: boolean | undefined) => boolean | null | undefined; defaultValue?: boolean | undefined; }
191+
SwaggerUI.config.typeCastMappings.withCredentials;
192+
87193
// $ExpectType SwaggerUIPreset
88-
const _basePreset = SwaggerUI.presets.base;
194+
SwaggerUI.presets.base;
89195
// $ExpectType SwaggerUIPreset
90-
const _apisPreset = SwaggerUI.presets.apis;
196+
SwaggerUI.presets.apis;
197+
198+
// $ExpectType SwaggerUIPlugin
199+
SwaggerUI.plugins.Auth;
200+
// $ExpectType SwaggerUIPlugin
201+
SwaggerUI.plugins.Configs;
202+
// $ExpectType SwaggerUIPlugin
203+
SwaggerUI.plugins.DeepLining;
204+
// $ExpectType SwaggerUIPlugin
205+
SwaggerUI.plugins.Err;
206+
// $ExpectType SwaggerUIPlugin
207+
SwaggerUI.plugins.Filter;
208+
// $ExpectType SwaggerUIPlugin
209+
SwaggerUI.plugins.Icons;
210+
// $ExpectType SwaggerUIPlugin
211+
SwaggerUI.plugins.JSONSchema5;
212+
// $ExpectType SwaggerUIPlugin
213+
SwaggerUI.plugins.JSONSchema5Samples;
214+
// $ExpectType SwaggerUIPlugin
215+
SwaggerUI.plugins.JSONSchema202012;
216+
// $ExpectType SwaggerUIPlugin
217+
SwaggerUI.plugins.JSONSchema202012Samples;
218+
// $ExpectType SwaggerUIPlugin
219+
SwaggerUI.plugins.Layout;
220+
// $ExpectType SwaggerUIPlugin
221+
SwaggerUI.plugins.Logs;
222+
// $ExpectType SwaggerUIPlugin
223+
SwaggerUI.plugins.OpenAPI30;
224+
// $ExpectType SwaggerUIPlugin
225+
SwaggerUI.plugins.OpenAPI31;
226+
// $ExpectType SwaggerUIPlugin
227+
SwaggerUI.plugins.OnComplete;
228+
// $ExpectType SwaggerUIPlugin
229+
SwaggerUI.plugins.RequestSnippets;
230+
// $ExpectType SwaggerUIPlugin
231+
SwaggerUI.plugins.Spec;
232+
// $ExpectType SwaggerUIPlugin
233+
SwaggerUI.plugins.SwaggerClient;
234+
// $ExpectType SwaggerUIPlugin
235+
SwaggerUI.plugins.Util;
236+
// $ExpectType SwaggerUIPlugin
237+
SwaggerUI.plugins.View;
238+
// $ExpectType SwaggerUIPlugin
239+
SwaggerUI.plugins.ViewLegacy;
240+
// $ExpectType SwaggerUIPlugin
241+
SwaggerUI.plugins.DownloadUrl;
242+
// $ExpectType SwaggerUIPlugin
243+
SwaggerUI.plugins.SyntaxHighlighting;
244+
// $ExpectType SwaggerUIPlugin
245+
SwaggerUI.plugins.Versions;
246+
// $ExpectType SwaggerUIPlugin
247+
SwaggerUI.plugins.SafeRender;
91248

92249
swaggerUI.initOAuth({});
93250
swaggerUI.preauthorizeApiKey("abc", "dec");

0 commit comments

Comments
 (0)