feat: update type definition & docs (#37234)

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

@@ -3,6 +3,7 @@
 // Definitions by: Haowen <https://github.com/haowen737>
 //                 Bryce <https://github.com/brycematheson1234>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
+// TypeScript Version: 2.1
 
 export {};
 export as namespace SwaggerUIDist;
@@ -13,26 +14,97 @@ export as namespace SwaggerUIDist;
 export function getAbsoluteFSPath(): string;
 export function absolutePath(): string;
 
-interface Url {
+export interface Url {
   url: string;
   name: string;
 }
 
-interface SwaggerUIBundle {
-  (a: {
+export interface Spec {
+  [k: string]: any;
+}
+
+export interface SwaggerConfigs {
+    /**
+     * URL to fetch external configuration document from.
+     */
     configUrl?: string;
+
+    /**
+     * If set to true, enables deep linking for tags and operations. See the Deep Linking documentation for more information.
+     */
     deepLinking?: boolean;
-    dom_id?: string;
-    domNode?: string;
+
+    /**
+     * REQUIRED if domNode is not provided. The ID of a DOM element inside which SwaggerUI will put its user interface.
+     */
+    dom_id?: string | null;
+
+    /**
+     *  REQUIRED if dom_id is not provided. The HTML DOM element inside which SwaggerUI will put its user interface. Overrides dom_id.
+     */
+    domNode?: string | HTMLElement | null;
+
+    /**
+     * An array of presets to use in Swagger UI. Usually, you'll want to include ApisPreset if you use this option.
+     */
     presets?: any[];
+
+    /**
+     * An array of plugin functions to use in Swagger UI.
+     */
     plugins?: any;
-    spec?: any;
-    url?: string;
+
+    /**
+     * A JavaScript object describing the OpenAPI definition. When used, the url parameter will not be parsed. This is useful for testing manually-generated definitions without hosting them.
+     */
+    spec?: Spec;
+
+    /**
+     * The URL pointing to API definition (normally swagger.json or swagger.yaml). Will be ignored if urls or spec is used.
+     */
+    url?: Url['url'];
+
+    /**
+     * An array of API definition objects ([{url: "<url1>", name: "<name1>"},{url: "<url2>", name: "<name2>"}]) used by Topbar plugin. When used and Topbar plugin is enabled,
+     * the url parameter will not be parsed. Names and URLs must be unique among all items in this array,
+     * since they're used as identifiers.
+     */
     urls?: Url[];
-    layout?: string;
-  }): any;
-  presets?: any;
-  plugins?: any;
+
+    /**
+     * The name of a component available via the plugin system to use as the top-level layout for Swagger UI.
+     */
+    layout?: 'BaseLayout';
+
+    /**
+     * Controls the default expansion setting for the operations and tags. It can be 'list' (expands only the tags), 'full' (expands the tags and operations) or 'none' (expands nothing).
+     */
+    docExpansion?: 'list' | 'full' | 'none';
+
+    /**
+     * If set, limits the number of tagged operations displayed to at most this many. The default is to show all operations.
+     */
+    maxDisplayedTags?: number;
+
+    /**
+     * Apply a sort to the operation list of each API.
+     * It can be 'alpha' (sort by paths alphanumerically), 'method' (sort by HTTP method) or a function (see Array.prototype.sort() to know how sort function works).
+     * Default is the order returned by the server unchanged.
+     */
+    operationsSorter?: () => void;
+
+    /**
+     *  Function to intercept remote definition, "Try it out", and OAuth 2.0 requests.
+     *  Accepts one argument requestInterceptor(request) and must return the modified request, or a Promise that resolves to the modified request.
+     */
+    requestInterceptor?: ((request: SwaggerRequest) => SwaggerRequest);
+
+    [k: string]: any;
+}
+
+export interface SwaggerUIBundle {
+  (a?: SwaggerConfigs): any;
+
   [k: string]: any;
 
   getConfigs(): SwaggerConfigs;
@@ -40,11 +112,6 @@ interface SwaggerUIBundle {
 
 export const SwaggerUIBundle: SwaggerUIBundle;
 
-interface SwaggerConfigs {
-  requestInterceptor: ((request: SwaggerRequest) => SwaggerRequest);
-  [k: string]: any;
-}
-
 export interface SwaggerRequest {
   url: string;
   credentials: string;

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

@@ -2,3 +2,5 @@ import * as SwaggerUIDist from "swagger-ui-dist";
 
 SwaggerUIDist.getAbsoluteFSPath(); // $ExpectType string
 SwaggerUIDist.absolutePath(); // $ExpectType string
+
+SwaggerUIDist.SwaggerUIBundle();

types/swagger-ui-dist/tsconfig.json

@@ -2,7 +2,8 @@
     "compilerOptions": {
         "module": "commonjs",
         "lib": [
-            "es6"
+            "es6",
+            "dom"
         ],
         "noImplicitAny": true,
         "noImplicitThis": true,