From 4fc501737daf1ff48cf40ec63e6fe84553af60eb Mon Sep 17 00:00:00 2001
From: neilbryson <neilbryson@users.noreply.github.com>
Date: Tue, 23 Jul 2019 03:37:25 +0800
Subject: [PATCH] [swagger-jsdoc] Made declarations more detailed  (#36977)

* update type definitions for swagger-jsdoc
* Made declarations more detailed
* Changed from ambient declarations to export
  - Interfaces are exported
  - Main function as default export

* Decrease minimum version of swagger-jsdoc to 3.0
---
 types/swagger-jsdoc/index.d.ts             | 45 +++++++++++++++++-----
 types/swagger-jsdoc/swagger-jsdoc-tests.ts | 23 ++++++-----
 2 files changed, 49 insertions(+), 19 deletions(-)

diff --git a/types/swagger-jsdoc/index.d.ts b/types/swagger-jsdoc/index.d.ts
index 673ac30579..96c8295ca2 100644
--- a/types/swagger-jsdoc/index.d.ts
+++ b/types/swagger-jsdoc/index.d.ts
@@ -1,16 +1,18 @@
-// Type definitions for Swagger-JSDoc
+// Type definitions for swagger-jsdoc 3.0
 // Project: https://github.com/surnet/swagger-jsdoc
 // Definitions by: Daniel Grove <https://github.com/drGrove>
+//                 Neil Bryson Cargamento <https://github.com/neilbryson>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
-// TypeScript Version: 2.2
+// TypeScript Version: 2.8
 
 /* =================== USAGE ===================
 
-    import * as express from "express"
-    import swaggerJSDoc = require('swagger-jsdoc');
-    const app = express()
+    import * as express from 'express';
+    import swaggerJSDoc, { Options }  from 'swagger-jsdoc';
 
-    let options = {
+    const app = express();
+
+    const options: Options = {
         swaggerDefinition: {
           info: {
             title: 'Hello World',
@@ -27,7 +29,7 @@
       }
     };
 
-    var spec = swaggerJSDoc(options);
+    const spec = swaggerJSDoc(options);
 
     app.get('/api-docs.json', function(req, res) {
       res.setHeader('Content-Type', 'application/json');
@@ -36,7 +38,30 @@
 
  =============================================== */
 
-declare module "swagger-jsdoc" {
-    function swaggerJSDoc(options?: any): any;
-    export = swaggerJSDoc;
+export interface ApiInformation {
+    description?: string;
+    title: string;
+    version: string;
 }
+
+export interface ServerInformation {
+    url: string;
+    [key: string]: any;
+}
+
+export interface SwaggerDefinition {
+    basePath?: string;
+    host?: string;
+    info: ApiInformation;
+    openapi?: string;
+    servers?: ReadonlyArray<ServerInformation>;
+    [key: string]: any;
+}
+
+export interface Options {
+    apis?: ReadonlyArray<string>;
+    swaggerDefinition: SwaggerDefinition;
+    [key: string]: any;
+}
+
+export default function swaggerJSDoc(options?: Options): any;
diff --git a/types/swagger-jsdoc/swagger-jsdoc-tests.ts b/types/swagger-jsdoc/swagger-jsdoc-tests.ts
index 4cf386e48a..2d67d811f5 100644
--- a/types/swagger-jsdoc/swagger-jsdoc-tests.ts
+++ b/types/swagger-jsdoc/swagger-jsdoc-tests.ts
@@ -1,21 +1,26 @@
-import express = require('express');
-import swaggerJSDoc = require('swagger-jsdoc');
+import * as express from 'express';
+import swaggerJSDoc, { Options } from 'swagger-jsdoc';
+
 const app = express();
 
-let options = {
+const options: Options = {
     swaggerDefinition: {
         info: {
             title: 'A test api',
-            version: '1.0.0'
-        }
-    }
+            version: '1.0.0',
+        },
+        host: 'localhost:3000',
+        basePath: '/',
+        openapi: '3.0.0',
+        servers: [{ url: '/api/v1' }, { url: '/api/v2' }],
+    },
+    apis: ['./example/routes*.js', './example/parameters.yaml'],
 };
 
-
-let swaggerSpec = swaggerJSDoc(options);
+const swaggerSpec = swaggerJSDoc(options);
 
 app.get('/api-docs.json', function(req, res) {
     res.send(swaggerSpec);
-})
+});
 
 app.listen(8888);