diff --git a/types/swagger-ui-express/index.d.ts b/types/swagger-ui-express/index.d.ts new file mode 100644 index 0000000000..f4165355fe --- /dev/null +++ b/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 +// 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; diff --git a/types/swagger-ui-express/swagger-ui-express-tests.ts b/types/swagger-ui-express/swagger-ui-express-tests.ts new file mode 100644 index 0000000000..f91128205c --- /dev/null +++ b/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)); diff --git a/types/swagger-ui-express/tsconfig.json b/types/swagger-ui-express/tsconfig.json new file mode 100644 index 0000000000..dfb989be63 --- /dev/null +++ b/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" + ] +} diff --git a/types/swagger-ui-express/tslint.json b/types/swagger-ui-express/tslint.json new file mode 100644 index 0000000000..f93cf8562a --- /dev/null +++ b/types/swagger-ui-express/tslint.json @@ -0,0 +1,3 @@ +{ + "extends": "dtslint/dt.json" +}