diff --git a/types/swagger-ui-express/index.d.ts b/types/swagger-ui-express/index.d.ts index 8fa2e7ab5b..97a0b66cd9 100644 --- a/types/swagger-ui-express/index.d.ts +++ b/types/swagger-ui-express/index.d.ts @@ -1,87 +1,108 @@ -// Type definitions for swagger-ui-express 3.0 +// Type definitions for swagger-ui-express 4.1 // Project: https://github.com/scottie1984/swagger-ui-express // Definitions by: Dmitry Rogozhny +// Florian Keller // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped // TypeScript Version: 2.8 -import { RequestHandler } from "express"; -import { ServeStaticOptions } from "serve-static"; +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[]; +export interface JsonObject { + [key: string]: any; } -declare const swaggerUiExpress: SwaggerUiExpress; +export interface SwaggerOptions { + [key: string]: any; +} -export = swaggerUiExpress; +export interface SwaggerUiOptions { + customCss?: string; + customCssUrl?: string; + customfavIcon?: string; + customJs?: string; + customSiteTitle?: string; + isExplorer?: boolean; + options?: SwaggerOptions; + swaggerUrl?: string; + swaggerUrls?: string[]; +} + +/** + * 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 customSiteTitle custom title for a page. + * @returns an express middleware function that returns the generated HTML page. + */ +export function setup( + swaggerDoc?: JsonObject, + opts?: SwaggerUiOptions, + options?: SwaggerOptions, + customCss?: string, + customfavIcon?: string, + swaggerUrl?: string, + customSiteTitle?: string, +): RequestHandler; + +/** @deprecated */ +export function setup(swaggerDoc?: JsonObject, isExplorer?: boolean): RequestHandler; + +/** + * Returns handlers for serving Swagger UI files. + * This includes the custom initialization JS file and static files of Swagger UI. + * + * @returns Express handlers that process requests and return files for Swagger UI. + */ +export const 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. + */ +export function 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 customSiteTitle custom title for a page. + * @returns the generated HTML page. + */ +export function generateHTML( + swaggerDoc?: JsonObject, + opts?: SwaggerUiOptions, + options?: SwaggerOptions, + customCss?: string, + customfavIcon?: string, + swaggerUrl?: string, + customSiteTitle?: string, +): string; + +/** @deprecated */ +export function generateHTML(swaggerDoc?: JsonObject, isExplorer?: boolean): RequestHandler; + +/** + * 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. + */ +export function serveFiles(swaggerDoc?: JsonObject, opts?: SwaggerUiOptions): RequestHandler[]; diff --git a/types/swagger-ui-express/swagger-ui-express-tests.ts b/types/swagger-ui-express/swagger-ui-express-tests.ts index f91128205c..e1ca950119 100644 --- a/types/swagger-ui-express/swagger-ui-express-tests.ts +++ b/types/swagger-ui-express/swagger-ui-express-tests.ts @@ -7,60 +7,82 @@ 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' } } } } } + 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', + 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.get( + '/api-docs', + swaggerUi.setup(swaggerDocument, undefined, 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')); +app.get( + '/api-docs-from-url', + swaggerUi.setup( + undefined, + undefined, + options, + '.swagger-ui .topbar { background-color: red }', + undefined, + '/swagger.json', + ), +); const swaggerUiOpts = { - explorer: false, - swaggerOptions: options, - customCss: '.swagger-ui .topbar { background-color: blue }' + 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' + 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.get('/api-docs-from-url-using-object', swaggerUi.setup(undefined, 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.get( + '/api-docs-with-null', + swaggerUi.setup(swaggerDocument, undefined, 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.get( + '/api-docs-split', + swaggerUi.setup(swaggerDocumentSplit, undefined, 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 }')); +app.get( + '/api-docs-with-opts/', + swaggerUi.setup(swaggerDocumentSplit, undefined, options, '.swagger-ui .topbar { background-color: orange }'), +); const swaggerHtml = swaggerUi.generateHTML(swaggerDocument, swaggerUiOpts);