From abffdc1c91c934601bdf984b9f00b6c556d613ee Mon Sep 17 00:00:00 2001 From: "d.rogozhny@gmail.com" Date: Sat, 23 Jun 2018 23:49:12 +0300 Subject: [PATCH 1/4] Add typings for swagger-ui-express package --- types/swagger-ui-express/index.d.ts | 86 +++++++++++++++++++ .../swagger-ui-express-tests.ts | 63 ++++++++++++++ types/swagger-ui-express/tsconfig.json | 22 +++++ types/swagger-ui-express/tslint.json | 6 ++ 4 files changed, 177 insertions(+) create mode 100644 types/swagger-ui-express/index.d.ts create mode 100644 types/swagger-ui-express/swagger-ui-express-tests.ts create mode 100644 types/swagger-ui-express/tsconfig.json create mode 100644 types/swagger-ui-express/tslint.json diff --git a/types/swagger-ui-express/index.d.ts b/types/swagger-ui-express/index.d.ts new file mode 100644 index 0000000000..bc319dde44 --- /dev/null +++ b/types/swagger-ui-express/index.d.ts @@ -0,0 +1,86 @@ +// 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"; + +declare namespace SwaggerUiExpress { + type JsonObject = { [key: string]: any; }; + type SwaggerUiOptions = { [key: string]: any; }; + type SwaggerOptions = { [key: string]: any; }; + + /** + * Creates a middleware function that returns the pre-generated html file for the Swagger UI page. + * + * @param {(JsonObject | null)} [swaggerDoc] json object with the API schema. + * @param {(SwaggerUiOptions | false | null)} [opts] swagger-ui-express options. + * @param {SwaggerOptions} [options] custom swagger options. + * @param {(string | false | null)} [customCss] string with a custom css to embed into the page. + * @param {(string | false | null)} [customfavIcon] link to a custom favicon. + * @param {(string | false | null)} [swaggerUrl] Url of the swagger API schema, can be specified instead of the swaggerDoc. + * @param {(string | false | null)} [customeSiteTitle] custom title for a page + * @returns {RequestHandler} an express middleware function that returns the generated html page. + */ + function 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 {Array} Express handlers that process requests and return files for Swagger UI. + */ + function serve(): Array; + + /** + * 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 {ServeStaticOptions} options options object that is passed to the express.static middleware. + * @returns {Array} Express handlers that process requests and return files for Swagger UI. + */ + function serveWithOptions(options: ServeStaticOptions): Array; + + /** + * Generates the custom html page for the UI API. + * + * @param {(JsonObject | null)} [swaggerDoc] json object with the API schema. + * @param {(SwaggerUiOptions | false | null)} [opts] swagger-ui-express options. + * @param {SwaggerOptions} [options] custom swagger options. + * @param {(string | false | null)} [customCss] string with a custom css to embed into the page. + * @param {(string | false | null)} [customfavIcon] link to a custom favicon. + * @param {(string | false | null)} [swaggerUrl] Url of the swagger API schema, can be specified instead of the swaggerDoc. + * @param {(string | false | null)} [customeSiteTitle] custom title for a page + * @returns {string} the generated html page. + */ + function 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 {JsonObject} [swaggerDoc] json object with the Swagger API schema. + * @param {SwaggerUiOptions} [opts] options to pass to Swagger UI. + * @returns {Array} Express handlers that process requests and return files for Swagger UI. + */ + function serveFiles(swaggerDoc?: JsonObject, opts?: SwaggerUiOptions): Array; +} + +export default 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..7338bd1f7b --- /dev/null +++ b/types/swagger-ui-express/swagger-ui-express-tests.ts @@ -0,0 +1,63 @@ +/** + * Tests are taken from the module's repository at https://github.com/scottie1984/swagger-ui-express/blob/master/test/testapp/app.js + */ + +import swaggerUi from "swagger-ui-express"; + +const express = require('express'); +const app = express(); +const swaggerDocument = require('./swagger.json'); +const swaggerDocumentSplit = require('./swagger-split.json'); + +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..0c7c25cbc4 --- /dev/null +++ b/types/swagger-ui-express/tsconfig.json @@ -0,0 +1,22 @@ +{ + "compilerOptions": { + "module": "commonjs", + "lib": [ + "es6" + ], + "noImplicitAny": true, + "noImplicitThis": true, + "strictNullChecks": 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..1e30988418 --- /dev/null +++ b/types/swagger-ui-express/tslint.json @@ -0,0 +1,6 @@ +{ + "extends": "dtslint/dt.json", + "rules": { + "no-var-requires": false + } +} From ba89491291595370b1e3c32a8dd6793462638428 Mon Sep 17 00:00:00 2001 From: "d.rogozhny@gmail.com" Date: Sun, 24 Jun 2018 00:06:14 +0300 Subject: [PATCH 2/4] Changes to pass tests and tslint --- types/swagger-ui-express/index.d.ts | 57 +++++++++++++------------- types/swagger-ui-express/tsconfig.json | 1 + 2 files changed, 29 insertions(+), 29 deletions(-) diff --git a/types/swagger-ui-express/index.d.ts b/types/swagger-ui-express/index.d.ts index bc319dde44..4af7308533 100644 --- a/types/swagger-ui-express/index.d.ts +++ b/types/swagger-ui-express/index.d.ts @@ -8,21 +8,21 @@ import { RequestHandler } from "express"; import { ServeStaticOptions } from "serve-static"; declare namespace SwaggerUiExpress { - type JsonObject = { [key: string]: any; }; - type SwaggerUiOptions = { [key: string]: any; }; - type SwaggerOptions = { [key: string]: any; }; + interface JsonObject { [key: string]: any; } + interface SwaggerUiOptions { [key: string]: any; } + interface SwaggerOptions { [key: string]: any; } /** * Creates a middleware function that returns the pre-generated html file for the Swagger UI page. * - * @param {(JsonObject | null)} [swaggerDoc] json object with the API schema. - * @param {(SwaggerUiOptions | false | null)} [opts] swagger-ui-express options. - * @param {SwaggerOptions} [options] custom swagger options. - * @param {(string | false | null)} [customCss] string with a custom css to embed into the page. - * @param {(string | false | null)} [customfavIcon] link to a custom favicon. - * @param {(string | false | null)} [swaggerUrl] Url of the swagger API schema, can be specified instead of the swaggerDoc. - * @param {(string | false | null)} [customeSiteTitle] custom title for a page - * @returns {RequestHandler} an express middleware function that returns the generated html 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. */ function setup(swaggerDoc?: JsonObject | null, opts?: SwaggerUiOptions | false | null, @@ -36,31 +36,31 @@ declare namespace SwaggerUiExpress { * Returns handlers for serving Swagger UI files. * This includes custom initialization js file and static files of Swagger UI. * - * @returns {Array} Express handlers that process requests and return files for Swagger UI. + * @returns Express handlers that process requests and return files for Swagger UI. */ - function serve(): Array; + function 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 {ServeStaticOptions} options options object that is passed to the express.static middleware. - * @returns {Array} Express handlers that process requests and return files for Swagger UI. + * @param options options object that is passed to the express.static middleware. + * @returns Express handlers that process requests and return files for Swagger UI. */ - function serveWithOptions(options: ServeStaticOptions): Array; + function serveWithOptions(options: ServeStaticOptions): RequestHandler[]; /** * Generates the custom html page for the UI API. * - * @param {(JsonObject | null)} [swaggerDoc] json object with the API schema. - * @param {(SwaggerUiOptions | false | null)} [opts] swagger-ui-express options. - * @param {SwaggerOptions} [options] custom swagger options. - * @param {(string | false | null)} [customCss] string with a custom css to embed into the page. - * @param {(string | false | null)} [customfavIcon] link to a custom favicon. - * @param {(string | false | null)} [swaggerUrl] Url of the swagger API schema, can be specified instead of the swaggerDoc. - * @param {(string | false | null)} [customeSiteTitle] custom title for a page - * @returns {string} the generated html 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 the generated html page. */ function generateHTML(swaggerDoc?: JsonObject | null, opts?: SwaggerUiOptions | false | null, @@ -70,17 +70,16 @@ declare namespace SwaggerUiExpress { 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 {JsonObject} [swaggerDoc] json object with the Swagger API schema. - * @param {SwaggerUiOptions} [opts] options to pass to Swagger UI. - * @returns {Array} Express handlers that process requests and return files for 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. */ - function serveFiles(swaggerDoc?: JsonObject, opts?: SwaggerUiOptions): Array; + function serveFiles(swaggerDoc?: JsonObject, opts?: SwaggerUiOptions): RequestHandler[]; } export default SwaggerUiExpress; diff --git a/types/swagger-ui-express/tsconfig.json b/types/swagger-ui-express/tsconfig.json index 0c7c25cbc4..c64deb2feb 100644 --- a/types/swagger-ui-express/tsconfig.json +++ b/types/swagger-ui-express/tsconfig.json @@ -7,6 +7,7 @@ "noImplicitAny": true, "noImplicitThis": true, "strictNullChecks": true, + "strictFunctionTypes": false, "baseUrl": "../", "typeRoots": [ "../" From aae9af48bd77a6c2e047d3c3ee8e01d05d1c88f8 Mon Sep 17 00:00:00 2001 From: "d.rogozhny@gmail.com" Date: Sun, 24 Jun 2018 00:12:55 +0300 Subject: [PATCH 3/4] Set strictFunctionTypes to true --- types/swagger-ui-express/tsconfig.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/types/swagger-ui-express/tsconfig.json b/types/swagger-ui-express/tsconfig.json index c64deb2feb..dfb989be63 100644 --- a/types/swagger-ui-express/tsconfig.json +++ b/types/swagger-ui-express/tsconfig.json @@ -7,7 +7,7 @@ "noImplicitAny": true, "noImplicitThis": true, "strictNullChecks": true, - "strictFunctionTypes": false, + "strictFunctionTypes": true, "baseUrl": "../", "typeRoots": [ "../" From 6dd05620c12e0dc37c7a6245fef6e62fef3dc158 Mon Sep 17 00:00:00 2001 From: "d.rogozhny@gmail.com" Date: Mon, 25 Jun 2018 09:14:45 +0300 Subject: [PATCH 4/4] Change export type and tslint rules --- types/swagger-ui-express/index.d.ts | 22 ++++++++++--------- .../swagger-ui-express-tests.ts | 22 +++++++++++-------- types/swagger-ui-express/tslint.json | 5 +---- 3 files changed, 26 insertions(+), 23 deletions(-) diff --git a/types/swagger-ui-express/index.d.ts b/types/swagger-ui-express/index.d.ts index 4af7308533..f4165355fe 100644 --- a/types/swagger-ui-express/index.d.ts +++ b/types/swagger-ui-express/index.d.ts @@ -7,11 +7,11 @@ import { RequestHandler } from "express"; import { ServeStaticOptions } from "serve-static"; -declare namespace SwaggerUiExpress { - interface JsonObject { [key: string]: any; } - interface SwaggerUiOptions { [key: string]: any; } - interface SwaggerOptions { [key: string]: any; } +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. * @@ -24,7 +24,7 @@ declare namespace SwaggerUiExpress { * @param customeSiteTitle custom title for a page * @returns an express middleware function that returns the generated html page. */ - function setup(swaggerDoc?: JsonObject | null, + setup(swaggerDoc?: JsonObject | null, opts?: SwaggerUiOptions | false | null, options?: SwaggerOptions, customCss?: string | false | null, @@ -38,7 +38,7 @@ declare namespace SwaggerUiExpress { * * @returns Express handlers that process requests and return files for Swagger UI. */ - function serve(): RequestHandler[]; + serve(): RequestHandler[]; /** * Returns handlers for serving Swagger UI files. @@ -48,7 +48,7 @@ declare namespace SwaggerUiExpress { * @param options options object that is passed to the express.static middleware. * @returns Express handlers that process requests and return files for Swagger UI. */ - function serveWithOptions(options: ServeStaticOptions): RequestHandler[]; + serveWithOptions(options: ServeStaticOptions): RequestHandler[]; /** * Generates the custom html page for the UI API. @@ -62,7 +62,7 @@ declare namespace SwaggerUiExpress { * @param customeSiteTitle custom title for a page * @returns the generated html page. */ - function generateHTML(swaggerDoc?: JsonObject | null, + generateHTML(swaggerDoc?: JsonObject | null, opts?: SwaggerUiOptions | false | null, options?: SwaggerOptions, customCss?: string | false | null, @@ -79,7 +79,9 @@ declare namespace SwaggerUiExpress { * @param opts options to pass to Swagger UI. * @returns Express handlers that process requests and return files for Swagger UI. */ - function serveFiles(swaggerDoc?: JsonObject, opts?: SwaggerUiOptions): RequestHandler[]; + serveFiles(swaggerDoc?: JsonObject, opts?: SwaggerUiOptions): RequestHandler[]; } -export default SwaggerUiExpress; +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 index 7338bd1f7b..f91128205c 100644 --- a/types/swagger-ui-express/swagger-ui-express-tests.ts +++ b/types/swagger-ui-express/swagger-ui-express-tests.ts @@ -2,21 +2,25 @@ * Tests are taken from the module's repository at https://github.com/scottie1984/swagger-ui-express/blob/master/test/testapp/app.js */ -import swaggerUi from "swagger-ui-express"; +import swaggerUi = require('swagger-ui-express'); +import express = require('express'); -const express = require('express'); const app = express(); -const swaggerDocument = require('./swagger.json'); -const swaggerDocumentSplit = require('./swagger-split.json'); +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: ",", + clientId: 'your-client-id1', + clientSecret: 'your-client-secret-if-required1', + realm: 'your-realms1', + appName: 'your-app-name1', + scopeSeparator: ',', additionalQueryStringParams: {} }, docExpansion: 'full', diff --git a/types/swagger-ui-express/tslint.json b/types/swagger-ui-express/tslint.json index 1e30988418..f93cf8562a 100644 --- a/types/swagger-ui-express/tslint.json +++ b/types/swagger-ui-express/tslint.json @@ -1,6 +1,3 @@ { - "extends": "dtslint/dt.json", - "rules": { - "no-var-requires": false - } + "extends": "dtslint/dt.json" }