feat: an extension adding a self-hosted REST API Explorer

Add a new package @loopback/rest-explorer that provides a self-hosted swagger-ui instance and disables the built-in swagger-ui redirect. Modify example projects to use @loopback/rest-explorer. Modify the CLI template to include self-hosted REST API Explorer in new applications.
loopbackio · Nov 15, 2018 · 4c165c7 · 4c165c7
1 parent 34af6a0
commit 4c165c7
Show file tree

Hide file tree

Showing 33 changed files with 605 additions and 10 deletions.
diff --git a/docs/site/Self-hosted-REST-API-Explorer.md b/docs/site/Self-hosted-REST-API-Explorer.md
@@ -0,0 +1,13 @@
+---
+lang: en
+title: 'Self-hosted REST API Explorer'
+keywords: LoopBack 4.0, LoopBack 4
+layout: readme
+source: loopback-next
+file: packages/rest-explorer/README.md
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/Self-hosted-rest-api-explorer.html
+summary:
+  A tutorial on using `@loopback/rest-explorer` to add a self-hosted REST API
+  Explorer
+---
diff --git a/docs/site/Server.md b/docs/site/Server.md
@@ -129,7 +129,7 @@ const app = new RestApplication({
 To disable redirect to the externally hosted API Explorer, set the config option
 `rest.apiExplorer.disabled` to `true`.
 
-````ts
+```ts
 const app = new RestApplication({
   rest: {
     apiExplorer: {
@@ -139,6 +139,15 @@ const app = new RestApplication({
 });
 ```
 
+### Use a self-hosted API Explorer
+
+Hosting the API Explorer at an external URL has a few downsides, for example a
+working internet connection is required to explore the API. As a recommended
+alternative, LoopBack comes with an extension that provides a self-hosted
+Explorer UI. Please refer to
+[Self-hosted REST API Explorer](./Self-hosted-rest-api-explorer.md) for more
+details.
+
 ### Enable HTTPS
 
 Enabling HTTPS for the LoopBack REST server is just a matter of specifying the
@@ -168,7 +177,7 @@ export async function main() {
   const url = app.restServer.url;
   console.log(`Server is running at ${url}`);
 }
-````
+```
 
 ### Customize CORS
 

diff --git a/docs/site/sidebars/lb4_sidebar.yml b/docs/site/sidebars/lb4_sidebar.yml
@@ -218,6 +218,11 @@ children:
 - title: 'Using Components'
   url: Using-components.html
   output: 'web, pdf'
+  children:
+
+  - title: Self-hosted REST API Explorer
+    url: Self-hosted-rest-api-explorer.html
+    output: 'web, pdf'
 
 - title: 'Calling other APIs'
   url: Calling-other-APIs-and-web-services.html

diff --git a/examples/soap-calculator/package.json b/examples/soap-calculator/package.json
@@ -43,6 +43,7 @@
     "@loopback/boot": "^1.0.4",
     "@loopback/context": "^1.1.0",
     "@loopback/core": "^1.1.0",
+    "@loopback/rest-explorer": "^0.1.0",
     "@loopback/openapi-v3": "^1.1.1",
     "@loopback/repository": "^1.0.4",
     "@loopback/rest": "^1.3.0",

diff --git a/examples/soap-calculator/src/application.ts b/examples/soap-calculator/src/application.ts
@@ -1,10 +1,11 @@
 import {BootMixin} from '@loopback/boot';
 import {ApplicationConfig} from '@loopback/core';
+import {RestExplorerComponent} from '@loopback/rest-explorer';
 import {RepositoryMixin} from '@loopback/repository';
 import {RestApplication} from '@loopback/rest';
 import {ServiceMixin} from '@loopback/service-proxy';
-import {MySequence} from './sequence';
 import * as path from 'path';
+import {MySequence} from './sequence';
 
 export class SoapCalculatorApplication extends BootMixin(
   ServiceMixin(RepositoryMixin(RestApplication)),
@@ -18,6 +19,8 @@ export class SoapCalculatorApplication extends BootMixin(
     // Set up default home page
     this.static('/', path.join(__dirname, '../../public'));
 
+    this.component(RestExplorerComponent);
+
     this.projectRoot = __dirname;
     // Customize @loopback/boot Booter Conventions here
     this.bootOptions = {

diff --git a/examples/soap-calculator/test/acceptance/home-page.acceptance.ts b/examples/soap-calculator/test/acceptance/home-page.acceptance.ts
@@ -25,4 +25,12 @@ describe('HomePage', () => {
       .expect(200)
       .expect('Content-Type', /text\/html/);
   });
+
+  it('exposes self-hosted explorer', async () => {
+    await client
+      .get('/explorer/')
+      .expect(200)
+      .expect('Content-Type', /text\/html/)
+      .expect(/<title>LoopBack API Explorer/);
+  });
 });
diff --git a/examples/todo-list/package.json b/examples/todo-list/package.json
@@ -37,6 +37,7 @@
     "@loopback/boot": "^1.0.4",
     "@loopback/context": "^1.1.0",
     "@loopback/core": "^1.1.0",
+    "@loopback/rest-explorer": "^0.1.0",
     "@loopback/openapi-v3": "^1.1.1",
     "@loopback/openapi-v3-types": "^1.0.1",
     "@loopback/repository": "^1.0.4",

diff --git a/examples/todo-list/src/application.ts b/examples/todo-list/src/application.ts
@@ -5,10 +5,11 @@
 
 import {BootMixin} from '@loopback/boot';
 import {ApplicationConfig} from '@loopback/core';
+import {RestExplorerComponent} from '@loopback/rest-explorer';
 import {RepositoryMixin} from '@loopback/repository';
 import {RestApplication} from '@loopback/rest';
-import {MySequence} from './sequence';
 import * as path from 'path';
+import {MySequence} from './sequence';
 
 export class TodoListApplication extends BootMixin(
   RepositoryMixin(RestApplication),
@@ -22,6 +23,8 @@ export class TodoListApplication extends BootMixin(
     // Set up default home page
     this.static('/', path.join(__dirname, '../../public'));
 
+    this.component(RestExplorerComponent);
+
     this.projectRoot = __dirname;
     // Customize @loopback/boot Booter Conventions here
     this.bootOptions = {

diff --git a/examples/todo-list/test/acceptance/home-page.acceptance.ts b/examples/todo-list/test/acceptance/home-page.acceptance.ts
@@ -25,4 +25,12 @@ describe('HomePage', () => {
       .expect(200)
       .expect('Content-Type', /text\/html/);
   });
+
+  it('exposes self-hosted explorer', async () => {
+    await client
+      .get('/explorer/')
+      .expect(200)
+      .expect('Content-Type', /text\/html/)
+      .expect(/<title>LoopBack API Explorer/);
+  });
 });
diff --git a/examples/todo/package.json b/examples/todo/package.json
@@ -37,6 +37,7 @@
     "@loopback/boot": "^1.0.4",
     "@loopback/context": "^1.1.0",
     "@loopback/core": "^1.1.0",
+    "@loopback/rest-explorer": "^0.1.0",
     "@loopback/openapi-v3": "^1.1.1",
     "@loopback/openapi-v3-types": "^1.0.1",
     "@loopback/repository": "^1.0.4",

diff --git a/examples/todo/src/application.ts b/examples/todo/src/application.ts
@@ -5,11 +5,12 @@
 
 import {BootMixin} from '@loopback/boot';
 import {ApplicationConfig} from '@loopback/core';
+import {RestExplorerComponent} from '@loopback/rest-explorer';
 import {RepositoryMixin} from '@loopback/repository';
 import {RestApplication} from '@loopback/rest';
 import {ServiceMixin} from '@loopback/service-proxy';
-import {MySequence} from './sequence';
 import * as path from 'path';
+import {MySequence} from './sequence';
 
 export class TodoListApplication extends BootMixin(
   ServiceMixin(RepositoryMixin(RestApplication)),
@@ -23,6 +24,8 @@ export class TodoListApplication extends BootMixin(
     // Set up default home page
     this.static('/', path.join(__dirname, '../../public'));
 
+    this.component(RestExplorerComponent);
+
     this.projectRoot = __dirname;
     // Customize @loopback/boot Booter Conventions here
     this.bootOptions = {

diff --git a/examples/todo/test/acceptance/home-page.acceptance.ts b/examples/todo/test/acceptance/home-page.acceptance.ts
@@ -25,4 +25,12 @@ describe('HomePage', () => {
       .expect(200)
       .expect('Content-Type', /text\/html/);
   });
+
+  it('exposes self-hosted explorer', async () => {
+    await client
+      .get('/explorer/')
+      .expect(200)
+      .expect('Content-Type', /text\/html/)
+      .expect(/<title>LoopBack API Explorer/);
+  });
 });
diff --git a/packages/cli/generators/app/templates/src/application.ts.ejs b/packages/cli/generators/app/templates/src/application.ts.ejs
@@ -1,14 +1,18 @@
 import {BootMixin} from '@loopback/boot';
 import {ApplicationConfig} from '@loopback/core';
+import {
+  RestExplorerBindings,
+  RestExplorerComponent,
+} from '@loopback/rest-explorer';
 <% if (project.repositories) { -%>
 import {RepositoryMixin} from '@loopback/repository';
 <% } -%>
 import {RestApplication} from '@loopback/rest';
 <% if (project.services) { -%>
 import {ServiceMixin} from '@loopback/service-proxy';
 <% } -%>
-import {MySequence} from './sequence';
 import * as path from 'path';
+import {MySequence} from './sequence';
 
 <% if (project.appClassWithMixins) { -%>
 export class <%= project.applicationName %> extends BootMixin(
@@ -28,6 +32,12 @@ export class <%= project.applicationName %> extends BootMixin(RestApplication) {
     // Set up default home page
     this.static('/', path.join(__dirname, '../../public'));
 
+    // Customize @loopback/rest-explorer configuration here
+    this.bind(RestExplorerBindings.CONFIG).to({
+      path: '/explorer',
+    });
+    this.component(RestExplorerComponent);
+
     this.projectRoot = __dirname;
     // Customize @loopback/boot Booter Conventions here
     this.bootOptions = {

diff --git a/packages/cli/generators/app/templates/test/acceptance/home-page.acceptance.ts.ejs b/packages/cli/generators/app/templates/test/acceptance/home-page.acceptance.ts.ejs
@@ -25,4 +25,12 @@ describe('HomePage', () => {
       .expect(200)
       .expect('Content-Type', /text\/html/);
   });
+
+  it('exposes self-hosted explorer', async () => {
+    await client
+      .get('/explorer/')
+      .expect(200)
+      .expect('Content-Type', /text\/html/)
+      .expect(/<title>LoopBack API Explorer/);
+  });
 });
diff --git a/packages/cli/generators/project/templates/package.json.ejs b/packages/cli/generators/project/templates/package.json.ejs
@@ -77,11 +77,12 @@
 <% if (project.repositories) { -%>
     "@loopback/repository": "<%= project.dependencies['@loopback/repository'] -%>",
 <% } -%>
-<% if (project.services) { -%>
     "@loopback/rest": "<%= project.dependencies['@loopback/rest'] -%>",
+<% if (project.services) { -%>
+    "@loopback/rest-explorer": "<%= project.dependencies['@loopback/rest-explorer'] -%>",
     "@loopback/service-proxy": "<%= project.dependencies['@loopback/service-proxy'] -%>"
 <% } else { -%>
-    "@loopback/rest": "<%= project.dependencies['@loopback/rest'] -%>"
+    "@loopback/rest-explorer": "<%= project.dependencies['@loopback/rest-explorer'] -%>"
 <% } -%>
 <% } else { /* NOT AN APPLICATION */-%>
     "@loopback/core": "<%= project.dependencies['@loopback/core'] -%>"

diff --git a/packages/cli/generators/project/templates/package.plain.json.ejs b/packages/cli/generators/project/templates/package.plain.json.ejs
@@ -72,7 +72,8 @@
     "@loopback/core": "<%= project.dependencies['@loopback/core'] -%>",
     "@loopback/openapi-v3": "<%= project.dependencies['@loopback/openapi-v3'] -%>",
     "@loopback/repository": "<%= project.dependencies['@loopback/repository'] -%>",
-    "@loopback/rest": "<%= project.dependencies['@loopback/rest'] -%>"
+    "@loopback/rest": "<%= project.dependencies['@loopback/rest'] -%>",
+    "@loopback/rest-explorer": "<%= project.dependencies['@loopback/rest-explorer'] -%>"
 <% } else { -%>
     "@loopback/core": "<%= project.dependencies['@loopback/core'] -%>"
 <% } -%>

diff --git a/packages/cli/package.json b/packages/cli/package.json
@@ -111,7 +111,8 @@
       "@loopback/http-caching-proxy": "^1.0.1",
       "@loopback/http-server": "^1.0.2",
       "@loopback/example-todo-list": "^1.1.1",
-      "@loopback/dist-util": "^0.4.0"
+      "@loopback/dist-util": "^0.4.0",
+      "@loopback/rest-explorer": "^0.1.0"
     }
   },
   "copyright.owner": "IBM Corp.",

diff --git a/packages/rest-explorer/.npmrc b/packages/rest-explorer/.npmrc
@@ -0,0 +1 @@
+package-lock=false
diff --git a/packages/rest-explorer/LICENSE b/packages/rest-explorer/LICENSE
@@ -0,0 +1,25 @@
+Copyright (c) IBM Corp. 2018. All Rights Reserved.
+Node module: @loopback/rest-explorer
+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.
diff --git a/packages/rest-explorer/README.md b/packages/rest-explorer/README.md
@@ -0,0 +1,63 @@
+# @loopback/rest-explorer
+
+This module contains a component adding a self-hosted REST API Explorer to
+LoopBack applications.
+
+## Installation
+
+```sh
+npm install --save @loopback/rest-explorer
+```
+
+## Basic use
+
+The component should be loaded in the constructor of your custom Application
+class. Applications scaffolded by recent versions of our `lb4` CLI tool have the
+self-hosted REST API Explorer pre-configured out of the box.
+
+Start by importing the component class:
+
+```ts
+import {RestExplorerComponent} from '@loopback/rest-explorer';
+```
+
+In the constructor, add the component to your application:
+
+```ts
+this.component(RestExplorerComponent);
+```
+
+By default, API Explorer is mounted at `/explorer`. This path can be customized
+via RestExplorer configuration as follows:
+
+```ts
+this.bind(RestExplorerBindings.CONFIG).to({
+  path: '/openapi/ui',
+});
+```
+
+_NOTE: The Explorer UI's visual style is not customizable yet. Our recommended
+solution is to create a fork of this module, make any style changes in the fork
+and publish the modified module under a different name. The
+[GitHub issue #2023](https://github.com/strongloop/loopback-next/issues/2023) is
+requesting a configuration option for customizing the visual style, please
+up-vote the issue and/or join the discussion if you are interested in this
+feature._
+
+## 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
diff --git a/packages/rest-explorer/docs.json b/packages/rest-explorer/docs.json
@@ -0,0 +1,9 @@
+{
+  "content": [
+    "index.ts",
+    "src/rest-explorer.component.ts",
+    "src/rest-explorer.keys.ts",
+    "src/rest-explorer.types.ts"
+  ],
+  "codeSectionDepth": 4
+}
diff --git a/packages/rest-explorer/index.d.ts b/packages/rest-explorer/index.d.ts
@@ -0,0 +1,6 @@
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: @loopback/rest-explorer
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+export * from './dist';
diff --git a/packages/rest-explorer/index.js b/packages/rest-explorer/index.js
@@ -0,0 +1,6 @@
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: @loopback/rest-explorer
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+module.exports = require('./dist');
diff --git a/packages/rest-explorer/index.ts b/packages/rest-explorer/index.ts
@@ -0,0 +1,8 @@
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: @loopback/rest-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';