diff --git a/pages/en/lb4/Application.md b/pages/en/lb4/Application.md index e7bea3197..539c3fe11 100644 --- a/pages/en/lb4/Application.md +++ b/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 diff --git a/pages/en/lb4/Defining-and-validating-the-API.md b/pages/en/lb4/Defining-and-validating-the-API.md index 0ed835e73..65cb22be7 100644 --- a/pages/en/lb4/Defining-and-validating-the-API.md +++ b/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... } diff --git a/pages/en/lb4/Routes.md b/pages/en/lb4/Routes.md index 6d0e8d679..936b0292e 100644 --- a/pages/en/lb4/Routes.md +++ b/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 diff --git a/pages/en/lb4/Sequence.md b/pages/en/lb4/Sequence.md index 92347320b..14cab99f9 100644 --- a/pages/en/lb4/Sequence.md +++ b/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 diff --git a/pages/en/lb4/Server.md b/pages/en/lb4/Server.md index d0e4d2135..35297a806 100644 --- a/pages/en/lb4/Server.md +++ b/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".