Move RestServer config out of async start (#621)

* move RestServer config out of start

* get rid of async start

* remove async start in Application.md

* add RestApplication tip

pages/en/lb4/Application.md

@@ -32,13 +32,17 @@ tasks as a part of your setup:
 import {Application} from '@loopback/core';
 import {RestComponent, RestServer} from '@loopback/rest';
 import {SamoflangeController, DoohickeyController} from './controllers';
-import {WidgetApi} from './apidef/';
 
 export class WidgetApplication extends Application {
   constructor() {
     // This is where you would pass configuration to the base constructor
     // (as well as handle your own!)
-    super();
+    super({
+      rest: {
+        port: 8080
+      }
+    });
+
     const app = this; // For clarity.
     // You can bind to the Application-level context here.
     // app.bind('foo').to(bar);
@@ -47,17 +51,6 @@ export class WidgetApplication extends Application {
     app.controller(DoohickeyController);
   }
 
-  async start() {
-    // This is where you would asynchronously retrieve servers, providers and
-    // other components to configure them before launch.
-    const server = await app.getServer(RestServer);
-    server.bind('rest.port').to(8080);
-    server.api(WidgetApi);
-    // The superclass start method will call start on all servers that are
-    // bound to the application.
-    return await super.start();
-  }
-
   async stop() {
     // This is where you would do whatever is necessary before stopping your
     // app (graceful closing of connections, flushing buffers, etc)
@@ -191,6 +184,15 @@ export class MyApplication extends RestApplication {
 ## Tips for application setup
 Here are some tips to help avoid common pitfalls and mistakes.
 
+### Extend from `RestApplication` when using `RestServer`
+If you want to use `RestServer` from our `@loopback/rest` package, we recommend you extend
+`RestApplication` in your app instead of manually binding `RestServer` or
+`RestComponent`. `RestApplication` already uses `RestComponent` and makes
+useful functions in `RestServer` like `handler()` available at the app level.
+This means you can call these `RestServer` functions to do all of your
+server-level setups in the app constructor without having to explicitly retrieve
+an instance of your server.
+
 ### Use unique bindings
 Use binding names that are prefixed with a unique string that does not overlap
 with loopback's bindings. As an example, if your application is built for

pages/en/lb4/Defining-and-validating-the-API.md

@@ -289,9 +289,17 @@ _.merge(spec, CategoryAPI);
 export default spec;
 ```
 
-You can then bind the full spec to the application using `server.spec()`. This is done on the server level, because each server instance can expose a different (sub)set of API.
+You can then bind the full spec to the application using `app.api()`.
+This works well for applications with a single REST server, because
+there is only one API definition involved.
 
-You also need to associate the controllers implementing the spec with the app using `app.controller(GreetController)`. This is not done on the server level because a controller may be used with multiple server instances, and types!
+If you are building an application with multiple REST servers,
+where each server provides a different API, then you need 
+to call `server.api()` instead.
+
+You also need to associate the controllers implementing the spec with the app
+using `app.controller(GreetController)`. This is not done on the server level
+because a controller may be used with multiple server instances, and types!
 
 ```ts
 // application.ts
@@ -302,20 +310,18 @@ import { ProductController, DealController, CategoryController } from "./control
 export class YourMicroservice extends RestApplication {
 
   constructor() {
-    super();
+    super({
+      rest: {
+        port: 3001
+      }
+    });
     const app = this;
 
     app.controller(ProductController);
     app.controller(DealController);
     app.controller(CategoryController);
-
-  }
-  async start() {
-    const server = await app.getServer(RestServer);
-    // inject your spec here!
-    server.api(spec);
-    server.bind("rest.port").to(3001);
-    await super.start();
+    //inject your spec
+    app.api(spec);
   }
   // etc...
 }

pages/en/lb4/Routes.md

@@ -79,7 +79,6 @@ application.
 import {RestApplication, RestServer, Route} from '@loopback/rest';
 import {OperationObject} from '@loopback/openapi-spec';
 
-const app = new RestApplication();
 const spec: OperationObject = {
   parameters: [{name: 'name', in: 'query', type: 'string'}],
   responses: {
@@ -95,12 +94,11 @@ function greet(name: string) {
   return `hello ${name}`;
 }
 
-(async function start() {
-  const server = await app.getServer(RestServer);
-  const route = new Route('get', '/', spec, greet);
-  server.route(route);
-  await app.start();
-})();
+const app = new RestApplication();
+const route = new Route('get', '/', spec, greet);
+app.route(route); // attaches route to RestServer
+
+app.start();
 ```
 
 ### Using Route decorators with controller methods
@@ -140,9 +138,7 @@ const app = new RestApplication();
 
 app.controller(GreetController);
 
-(async function start() {
-  await app.start();
-})();
+app.start();
 ```
 
 ## Invoking operations using Routes

pages/en/lb4/Sequence.md

@@ -86,20 +86,16 @@ class MySequence extends DefaultSequence {
 }
 ```
 
-In order for LoopBack to use your custom sequence, you must register it on any
-applicable `Server` instances before starting your `Application`:
+In order for LoopBack to use your custom sequence, you must register it
+before starting your `Application`:
 
 ```js
 import {RestApplication, RestServer} from '@loopback/rest';
 
 const app = new RestApplication();
+app.sequence(MySequencce);
 
-// or
-(async function start() {
-  const server = await app.getServer(RestServer);
-  server.sequence(MySequence);
-  await app.start();
-})();
+app.start();
 ```
 
 ## Advanced topics

pages/en/lb4/Server.md

@@ -23,16 +23,18 @@ import {RestApplication, RestServer} from '@loopback/rest';
 export class HelloWorldApp extends RestApplication {
   constructor() {
     super();
+    // give our RestServer instance a sequence handler function which
+    // returns the Hello World string for all requests
+    // with RestApplication, handler function can be registered
+    // at app level
+    app.handler((sequence, request, response) => {
+      sequence.send(response, 'Hello World!');
+    });
   }
 
   async start() {
     // get a singleton HTTP server instance
     const rest = await this.getServer(RestServer);
-    // give our RestServer instance a sequence handler function which
-    // returns the Hello World string for all requests
-    rest.handler((sequence, request, response) => {
-      sequence.send(response, 'Hello World!');
-    });
     // call start on application class, which in turn starts all registered
     // servers
     await super.start();
@@ -48,9 +50,10 @@ export class HelloWorldApp extends RestApplication {
 You can add server instances to your application via the `app.server()` method individually or as an array using `app.servers()` method. Using `app.server()` allows you to uniquely name your binding key for your specific server instance. The following example demonstrates how to use these functions:
 
 ```ts
-import {RestApplication, RestServer} from '@loopback/rest';
+import {Application} from '@loopback/core';
+import {RestServer} from '@loopback/rest';
 
-export class HelloWorldApp extends RestApplication {
+export class HelloWorldApp extends Application {
   constructor() {
     super();
     // This server instance will be bound under "servers.fooServer".