feat(explorer): add a package for local API Explorer UI

packages/explorer/.npmrc

@@ -0,0 +1 @@
+package-lock=false

packages/explorer/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) IBM Corp. 2017,2018. All Rights Reserved.
+Node module: @loopback/metadata
+This project is licensed under the MIT License, full text below.
+
+--------
+
+MIT license
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

packages/explorer/README.md

@@ -0,0 +1,27 @@
+# @loopback/explorer
+
+This module contains a handler to serve API Explorer
+
+## Installation
+
+```sh
+npm install --save @loopback/explorer
+```
+
+## Contributions
+
+- [Guidelines](https://github.com/strongloop/loopback-next/blob/master/docs/CONTRIBUTING.md)
+- [Join the team](https://github.com/strongloop/loopback-next/issues/110)
+
+## Tests
+
+Run `npm test` from the root folder.
+
+## Contributors
+
+See
+[all contributors](https://github.com/strongloop/loopback-next/graphs/contributors).
+
+## License
+
+MIT

packages/explorer/docs.json

@@ -0,0 +1,7 @@
+{
+  "content": [
+    "index.ts",
+    "src/explorer.ts"
+  ],
+  "codeSectionDepth": 4
+}

packages/explorer/index.d.ts

@@ -0,0 +1,6 @@
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: @loopback/explorer
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+export * from './dist8';

packages/explorer/index.js

@@ -0,0 +1,6 @@
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: @loopback/explorer
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+module.exports = require('@loopback/dist-util').loadDist(__dirname);

packages/explorer/index.ts

@@ -0,0 +1,8 @@
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: @loopback/explorer
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+// DO NOT EDIT THIS FILE
+// Add any additional (re)exports to src/index.ts instead.
+export * from './src';

packages/explorer/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@loopback/explorer",
+  "version": "0.1.0",
+  "description": "LoopBack's API Explorer",
+  "engines": {
+    "node": ">=8.9"
+  },
+  "scripts": {
+    "build:all-dist": "npm run build:dist8 && npm run build:dist10",
+    "build:apidocs": "lb-apidocs",
+    "build": "lb-tsc",
+    "build:dist8": "lb-tsc es2017",
+    "build:dist10": "lb-tsc es2018",
+    "clean": "lb-clean loopback-explorer*.tgz dist* package api-docs",
+    "pretest": "npm run build",
+    "integration": "lb-mocha \"DIST/test/integration/**/*.js\"",
+    "test": "lb-mocha \"DIST/test/unit/**/*.js\" \"DIST/test/integration/**/*.js\"",
+    "unit": "lb-mocha \"DIST/test/unit/**/*.js\"",
+    "verify": "npm pack && tar xf loopback-explorer*.tgz && tree package && npm run clean"
+  },
+  "author": "IBM",
+  "copyright.owner": "IBM Corp.",
+  "license": "MIT",
+  "dependencies": {
+    "@types/express": "^4.16.0",
+    "ejs": "^2.6.1",
+    "serve-static": "^1.13.2",
+    "swagger-ui-dist": "^3.18.2"
+  },
+  "devDependencies": {
+    "@loopback/build": "^0.7.1",
+    "@loopback/dist-util": "^0.3.6",
+    "@loopback/testlab": "^0.11.5",
+    "@types/ejs": "^2.6.0",
+    "@types/node": "^10.1.1",
+    "@types/serve-static": "^1.13.2",
+    "express": "^4.16.3"
+  },
+  "keywords": [
+    "LoopBack",
+    "Explorer",
+    "Swagger"
+  ],
+  "files": [
+    "README.md",
+    "index.js",
+    "index.d.ts",
+    "dist*/src",
+    "dist*/index*",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/strongloop/loopback-next.git"
+  }
+}

packages/explorer/src/explorer.ts

@@ -0,0 +1,64 @@
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: @loopback/explorer
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+const swaggerUI = require('swagger-ui-dist');
+
+import * as path from 'path';
+import * as fs from 'fs';
+
+import {Handler} from 'express';
+import * as serveStatic from 'serve-static';
+import * as ejs from 'ejs';
+
+/**
+ * Options to configure API Explorer UI
+ */
+export type ApiExplorerUIOptions = {
+  /**
+   * URL to the OpenAPI spec
+   */
+  openApiSpecUrl?: string;
+
+  /**
+   * Custom EJS template for index.html
+   */
+  indexHtmlTemplate?: string;
+
+  /**
+   * Options for serve-static middleware
+   */
+  serveStaticOptions?: serveStatic.ServeStaticOptions;
+};
+
+/**
+ * Mount the API Explorer UI (swagger-ui) to the given express router
+ * @param options
+ */
+export function apiExplorerUI(options: ApiExplorerUIOptions = {}): Handler {
+  const openApiSpecUrl = options.openApiSpecUrl || '/openapi.json';
+  const indexHtml =
+    options.indexHtmlTemplate || path.resolve(__dirname, './index.html.ejs');
+  const template = fs.readFileSync(indexHtml, 'utf-8');
+  const templateFn = ejs.compile(template);
+  const uiHandler = serveStatic(
+    swaggerUI.getAbsoluteFSPath(),
+    options.serveStaticOptions,
+  );
+
+  return (req, res, next) => {
+    if (req.path === '/' || req.path === '/index.html') {
+      const data = {
+        openApiSpecUrl,
+      };
+      const homePage = templateFn(data);
+      res
+        .status(200)
+        .contentType('text/html')
+        .send(homePage);
+    } else {
+      uiHandler(req, res, next);
+    }
+  };
+}

packages/explorer/src/index.html.ejs

@@ -0,0 +1,64 @@
+<!-- HTML for static distribution bundle build -->
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <title>LoopBack API Explorer</title>
+  <link rel="stylesheet" type="text/css" href="./swagger-ui.css">
+  <link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
+  <link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />
+  <style>
+    html {
+      box-sizing: border-box;
+      overflow: -moz-scrollbars-vertical;
+      overflow-y: scroll;
+    }
+
+    *,
+    *:before,
+    *:after {
+      box-sizing: inherit;
+    }
+
+    body {
+      margin: 0;
+      background: #fafafa;
+    }
+  </style>
+</head>
+
+<body>
+  <div id="swagger-ui"></div>
+
+  <script src="./swagger-ui-bundle.js"> </script>
+  <script src="./swagger-ui-standalone-preset.js"> </script>
+  <script>
+    window.onload = function () {
+
+      // Build a system
+      const ui = SwaggerUIBundle({
+        url: "<%- openApiSpecUrl %>",
+        dom_id: '#swagger-ui',
+        deepLinking: true,
+        filter: true,
+        defaultModelsExpandDepth: 0,
+        defaultModelExpandDepth: 0,
+        presets: [
+          SwaggerUIBundle.presets.apis,
+          // SwaggerUIStandalonePreset
+          SwaggerUIStandalonePreset.slice(1) // Disable the top bar
+        ],
+        plugins: [
+          SwaggerUIBundle.plugins.DownloadUrl
+        ],
+        layout: "StandaloneLayout"
+
+      })
+
+      window.ui = ui
+    }
+  </script>
+</body>
+
+</html>

packages/explorer/src/index.ts

@@ -0,0 +1,6 @@
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: @loopback/explorer
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+export * from './explorer';

packages/explorer/test/integration/explorer.integration.ts

@@ -0,0 +1,57 @@
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: @loopback/explorer
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import {createClientForHandler} from '@loopback/testlab';
+import {apiExplorerUI} from '../../src/explorer';
+import * as express from 'express';
+import * as path from 'path';
+
+describe('API Explorer UI', () => {
+  let app: express.Application;
+  let router: express.Router;
+
+  beforeEach(() => {
+    app = express();
+    router = express.Router();
+    app.use('/api-explorer', router);
+  });
+
+  it('mounts API explorer UI', () => {
+    router.use(apiExplorerUI());
+    const test = createClientForHandler(app);
+    test
+      .get('/api-explorer')
+      .expect('content-type', 'text/html')
+      .expect(200, '<title>LoopBack API Explorer</title>');
+
+    test.get('/api-explorer/swagger-ui-bundle.js').expect(200);
+  });
+
+  it('accepts API explorer UI options - openApiSpecUrl', () => {
+    router.use(
+      apiExplorerUI({
+        openApiSpecUrl: 'https://localhost:8080/openapi.json',
+      }),
+    );
+    const test = createClientForHandler(app);
+    test
+      .get('/api-explorer')
+      .expect('content-type', 'text/html')
+      .expect(200, 'https://localhost:8080/openapi.json');
+  });
+
+  it('accepts API explorer UI options - indexHtmlTemplate', () => {
+    router.use(
+      apiExplorerUI({
+        indexHtmlTemplate: path.resolve(__dirname, 'test.html.ejs'),
+      }),
+    );
+    const test = createClientForHandler(app);
+    test
+      .get('/api-explorer')
+      .expect('content-type', 'text/html')
+      .expect(200, '<title>Test API Explorer</title>');
+  });
+});