Merge pull request #26776 from dmitryrogozhny/swagger-ui-express

Add new type declarations for the swagger-ui-express package

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

@@ -0,0 +1,87 @@
+// Type definitions for swagger-ui-express 3.0
+// Project: https://github.com/scottie1984/swagger-ui-express
+// Definitions by: Dmitry Rogozhny <https://github.com/dmitryrogozhny>
+// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
+// TypeScript Version: 2.8
+
+import { RequestHandler } from "express";
+import { ServeStaticOptions } from "serve-static";
+
+interface JsonObject { [key: string]: any; }
+interface SwaggerUiOptions { [key: string]: any; }
+interface SwaggerOptions { [key: string]: any; }
+
+interface SwaggerUiExpress {
+    /**
+     * Creates a middleware function that returns the pre-generated html file for the Swagger UI page.
+     *
+     * @param swaggerDoc json object with the API schema.
+     * @param opts swagger-ui-express options.
+     * @param options custom swagger options.
+     * @param customCss string with a custom css to embed into the page.
+     * @param customfavIcon link to a custom favicon.
+     * @param swaggerUrl Url of the swagger API schema, can be specified instead of the swaggerDoc.
+     * @param customeSiteTitle custom title for a page
+     * @returns an express middleware function that returns the generated html page.
+     */
+    setup(swaggerDoc?: JsonObject | null,
+        opts?: SwaggerUiOptions | false | null,
+        options?: SwaggerOptions,
+        customCss?: string | false | null,
+        customfavIcon?: string | false | null,
+        swaggerUrl?: string | false | null,
+        customeSiteTitle?: string | false | null): RequestHandler;
+
+    /**
+     * Returns handlers for serving Swagger UI files.
+     * This includes custom initialization js file and static files of Swagger UI.
+     *
+     * @returns Express handlers that process requests and return files for Swagger UI.
+     */
+    serve(): RequestHandler[];
+
+    /**
+     * Returns handlers for serving Swagger UI files.
+     * This includes custom initialization js file and static files of Swagger UI.
+     * Additional options are passed to the express.static middleware.
+     *
+     * @param options options object that is passed to the express.static middleware.
+     * @returns Express handlers that process requests and return files for Swagger UI.
+     */
+    serveWithOptions(options: ServeStaticOptions): RequestHandler[];
+
+    /**
+     * Generates the custom html page for the UI API.
+     *
+     * @param swaggerDoc json object with the API schema.
+     * @param opts swagger-ui-express options.
+     * @param options custom swagger options.
+     * @param customCss string with a custom css to embed into the page.
+     * @param customfavIcon link to a custom favicon.
+     * @param swaggerUrl Url of the swagger API schema, can be specified instead of the swaggerDoc.
+     * @param customeSiteTitle custom title for a page
+     * @returns the generated html page.
+     */
+    generateHTML(swaggerDoc?: JsonObject | null,
+        opts?: SwaggerUiOptions | false | null,
+        options?: SwaggerOptions,
+        customCss?: string | false | null,
+        customfavIcon?: string | false | null,
+        swaggerUrl?: string | false | null,
+        customeSiteTitle?: string | false | null): string;
+
+    /**
+     * Returns handlers for serving Swagger UI files.
+     * This includes custom initialization js file and static files of Swagger UI.
+     * Additional options object is passed to Swagger UI.
+     *
+     * @param swaggerDoc json object with the Swagger API schema.
+     * @param opts options to pass to Swagger UI.
+     * @returns Express handlers that process requests and return files for Swagger UI.
+     */
+    serveFiles(swaggerDoc?: JsonObject, opts?: SwaggerUiOptions): RequestHandler[];
+}
+
+declare const swaggerUiExpress: SwaggerUiExpress;
+
+export = swaggerUiExpress;

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

@@ -0,0 +1,67 @@
+/**
+ * Tests are taken from the module's repository at https://github.com/scottie1984/swagger-ui-express/blob/master/test/testapp/app.js
+ */
+
+import swaggerUi = require('swagger-ui-express');
+import express = require('express');
+
+const app = express();
+const swaggerDocument = {
+	swagger: '2.0',
+	info: { version: '1.0.0', title: 'Example API' },
+	paths: { '/user': { get: { responses: { 200: { description: 'all users' } } } } }
+};
+const swaggerDocumentSplit = swaggerDocument;
+
+const options = {
+	validatorUrl: null,
+	oauth: {
+		clientId: 'your-client-id1',
+		clientSecret: 'your-client-secret-if-required1',
+		realm: 'your-realms1',
+		appName: 'your-app-name1',
+		scopeSeparator: ',',
+		additionalQueryStringParams: {}
+	},
+	docExpansion: 'full',
+};
+
+app.use('/api-docs', swaggerUi.serve);
+app.get('/api-docs', swaggerUi.setup(swaggerDocument, false, options, '.swagger-ui .topbar { background-color: red }'));
+
+app.use('/api-docs-from-url', swaggerUi.serve);
+app.get('/api-docs-from-url', swaggerUi.setup(null, false, options, '.swagger-ui .topbar { background-color: red }', null, '/swagger.json'));
+
+const swaggerUiOpts = {
+	explorer: false,
+	swaggerOptions: options,
+	customCss: '.swagger-ui .topbar { background-color: blue }'
+};
+
+app.use('/api-docs-using-object', swaggerUi.serve);
+app.get('/api-docs-using-object', swaggerUi.setup(swaggerDocument, swaggerUiOpts));
+
+const swaggerUiOpts2 = {
+	explorer: false,
+	swaggerOptions: options,
+	customCss: '.swagger-ui .topbar { background-color: pink }',
+	swaggerUrl: '/swagger.json',
+	customJs: '/my-custom.js',
+	operationsSorter: 'alpha'
+};
+
+app.use('/api-docs-from-url-using-object', swaggerUi.serve);
+app.get('/api-docs-from-url-using-object', swaggerUi.setup(null, swaggerUiOpts2));
+
+app.use('/api-docs-with-null', swaggerUi.serve);
+app.get('/api-docs-with-null', swaggerUi.setup(swaggerDocument, null, options, '.swagger-ui .topbar { background-color: orange }'));
+
+app.use('/api-docs-split', swaggerUi.serve);
+app.get('/api-docs-split', swaggerUi.setup(swaggerDocumentSplit, null, options, '.swagger-ui .topbar { background-color: orange }'));
+
+app.use('/api-docs-with-opts/', swaggerUi.serveWithOptions({ redirect: false }));
+app.get('/api-docs-with-opts/', swaggerUi.setup(swaggerDocumentSplit, null, options, '.swagger-ui .topbar { background-color: orange }'));
+
+const swaggerHtml = swaggerUi.generateHTML(swaggerDocument, swaggerUiOpts);
+
+app.use('/api-docs-html1', swaggerUi.serveFiles(swaggerDocument, swaggerUiOpts));

types/swagger-ui-express/tsconfig.json

@@ -0,0 +1,23 @@
+{
+    "compilerOptions": {
+        "module": "commonjs",
+        "lib": [
+            "es6"
+        ],
+        "noImplicitAny": true,
+        "noImplicitThis": true,
+        "strictNullChecks": true,
+        "strictFunctionTypes": true,
+        "baseUrl": "../",
+        "typeRoots": [
+            "../"
+        ],
+        "types": [],
+        "noEmit": true,
+        "forceConsistentCasingInFileNames": true
+    },
+    "files": [
+        "index.d.ts",
+        "swagger-ui-express-tests.ts"
+    ]
+}

types/swagger-ui-express/tslint.json

@@ -0,0 +1,3 @@
+{
+    "extends": "dtslint/dt.json"
+}