feat(rest): app.route() and app.api()

Enhance `RestApplication` class to provide shortcuts for registering
routes and configuring the master OpenAPI spec.

Fix restApp.sequence() - modify RestServer to inherit the sequence
binding from the application, modify RestComponent to register the
DefaultSequence at the app level (instead of RestServer level).

Similarly, modify RestServer to inherit the API_SPEC binding from
the application, modify RestComponent to register an empty spec at
the app level (instead of RestServer level).

Author: bajtos

packages/rest/src/rest-application.ts

@@ -9,6 +9,9 @@ import {SequenceHandler, SequenceFunction} from './sequence';
 import {Binding, Constructor} from '@loopback/context';
 import {format} from 'util';
 import {RestBindings} from './keys';
+import {RouteEntry, RestServer} from '.';
+import {ControllerClass} from './router/routing-table';
+import {OperationObject, OpenApiSpec} from '@loopback/openapi-spec';
 
 export const ERR_NO_MULTI_SERVER = format(
   'RestApplication does not support multiple servers!',
@@ -46,7 +49,79 @@ export class RestApplication extends Application {
   handler(handlerFn: SequenceFunction) {
     // FIXME(kjdelisle): I attempted to mimic the pattern found in RestServer
     // with no success, so until I've got a better way, this is functional.
-    const server = this.getSync('servers.RestServer');
+    const server: RestServer = this.getSync('servers.RestServer');
     server.handler(handlerFn);
   }
+
+  /**
+   * Register a new Controller-based route.
+   *
+   * ```ts
+   * class MyController {
+   *   greet(name: string) {
+   *     return `hello ${name}`;
+   *   }
+   * }
+   * app.route('get', '/greet', operationSpec, MyController, 'greet');
+   * ```
+   *
+   * @param verb HTTP verb of the endpoint
+   * @param path URL path of the endpoint
+   * @param spec The OpenAPI spec describing the endpoint (operation)
+   * @param controller Controller constructor
+   * @param methodName The name of the controller method
+   */
+  route(
+    verb: string,
+    path: string,
+    spec: OperationObject,
+    controller: ControllerClass,
+    methodName: string,
+  ): Binding;
+
+  /**
+   * Register a new route.
+   *
+   * ```ts
+   * function greet(name: string) {
+   *  return `hello ${name}`;
+   * }
+   * const route = new Route('get', '/', operationSpec, greet);
+   * app.route(route);
+   * ```
+   *
+   * @param route The route to add.
+   */
+  route(route: RouteEntry): Binding;
+
+  route(
+    routeOrVerb: RouteEntry | string,
+    path?: string,
+    spec?: OperationObject,
+    controller?: ControllerClass,
+    methodName?: string,
+  ): Binding {
+    // FIXME(bajtos): This is a workaround based on app.handler() above
+    const server: RestServer = this.getSync('servers.RestServer');
+    if (typeof routeOrVerb === 'object') {
+      return server.route(routeOrVerb);
+    } else {
+      return server.route(routeOrVerb, path!, spec!, controller!, methodName!);
+    }
+  }
+
+  /**
+   * Set the OpenAPI specification that defines the REST API schema for this
+   * application. All routes, parameter definitions and return types will be
+   * defined in this way.
+   *
+   * Note that this will override any routes defined via decorators at the
+   * controller level (this function takes precedent).
+   *
+   * @param {OpenApiSpec} spec The OpenAPI specification, as an object.
+   * @returns {Binding}
+   */
+  api(spec: OpenApiSpec): Binding {
+    return this.bind(RestBindings.API_SPEC).to(spec);
+  }
 }

packages/rest/src/rest-component.ts

@@ -23,6 +23,8 @@ import {
   SendProvider,
 } from './providers';
 import {RestServer, RestServerConfig} from './rest-server';
+import {DefaultSequence} from '.';
+import {createEmptyApiSpec} from '@loopback/openapi-spec';
 
 export class RestComponent implements Component {
   providers: ProviderMap = {
@@ -45,7 +47,8 @@ export class RestComponent implements Component {
     @inject(CoreBindings.APPLICATION_INSTANCE) app: Application,
     @inject(RestBindings.CONFIG) config?: RestComponentConfig,
   ) {
-    if (!config) config = {};
+    app.bind(RestBindings.SEQUENCE).toClass(DefaultSequence);
+    app.bind(RestBindings.API_SPEC).to(createEmptyApiSpec());
   }
 }
 

packages/rest/src/rest-server.ts

@@ -9,11 +9,7 @@ import {safeDump} from 'js-yaml';
 import {Binding, Context, Constructor, inject} from '@loopback/context';
 import {Route, ControllerRoute, RouteEntry} from './router/routing-table';
 import {ParsedRequest} from './internal-types';
-import {
-  OpenApiSpec,
-  createEmptyApiSpec,
-  OperationObject,
-} from '@loopback/openapi-spec';
+import {OpenApiSpec, OperationObject} from '@loopback/openapi-spec';
 import {ServerRequest, ServerResponse, createServer} from 'http';
 import * as Http from 'http';
 import {Application, CoreBindings, Server} from '@loopback/core';
@@ -141,9 +137,10 @@ export class RestServer extends Context implements Server {
     }
     this.bind(RestBindings.PORT).to(options.port);
     this.bind(RestBindings.HOST).to(options.host);
-    this.api(createEmptyApiSpec());
 
-    this.sequence(options.sequence ? options.sequence : DefaultSequence);
+    if (options.sequence) {
+      this.sequence(options.sequence);
+    }
 
     this.handleHttp = (req: ServerRequest, res: ServerResponse) => {
       try {

packages/rest/test/acceptance/routing/routing.acceptance.ts

@@ -10,6 +10,7 @@ import {
   RestBindings,
   RestServer,
   RestComponent,
+  RestApplication,
 } from '../../..';
 
 import {api, get, param} from '@loopback/openapi-v2';
@@ -487,6 +488,83 @@ describe('Routing', () => {
     await client.get('/greet?name=world').expect(200, 'hello world');
   });
 
+  describe('RestApplication', () => {
+    it('supports function-based routes declared via app.route()', async () => {
+      const app = new RestApplication();
+
+      const routeSpec = <OperationObject>{
+        parameters: [
+          <ParameterObject>{name: 'name', in: 'query', type: 'string'},
+        ],
+        responses: {
+          200: <ResponseObject>{
+            description: 'greeting text',
+            schema: {type: 'string'},
+          },
+        },
+      };
+
+      function greet(name: string) {
+        return `hello ${name}`;
+      }
+
+      const route = new Route('get', '/greet', routeSpec, greet);
+      app.route(route);
+
+      const server = await givenAServer(app);
+      const client = whenIMakeRequestTo(server);
+      await client.get('/greet?name=world').expect(200, 'hello world');
+    });
+
+    it('supports controller routes declared via app.api()', async () => {
+      const app = new RestApplication();
+
+      class MyController {
+        greet(name: string) {
+          return `hello ${name}`;
+        }
+      }
+
+      const spec = anOpenApiSpec()
+        .withOperation(
+          'get',
+          '/greet',
+          anOperationSpec()
+            .withParameter({name: 'name', in: 'query', type: 'string'})
+            .withExtension('x-operation-name', 'greet')
+            .withExtension('x-controller-name', 'MyController'),
+        )
+        .build();
+
+      app.api(spec);
+      app.controller(MyController);
+
+      const server = await givenAServer(app);
+      const client = whenIMakeRequestTo(server);
+      await client.get('/greet?name=world').expect(200, 'hello world');
+    });
+
+    it('supports controller routes defined via app.route()', async () => {
+      const app = new RestApplication();
+
+      class MyController {
+        greet(name: string) {
+          return `hello ${name}`;
+        }
+      }
+
+      const spec = anOperationSpec()
+        .withParameter({name: 'name', in: 'query', type: 'string'})
+        .build();
+
+      app.route('get', '/greet', spec, MyController, 'greet');
+
+      const server = await givenAServer(app);
+      const client = whenIMakeRequestTo(server);
+      await client.get('/greet?name=world').expect(200, 'hello world');
+    });
+  });
+
   /* ===== HELPERS ===== */
 
   function givenAnApplication() {

packages/rest/test/acceptance/sequence/sequence.acceptance.ts

@@ -16,6 +16,7 @@ import {
   RestBindings,
   RestServer,
   RestComponent,
+  RestApplication,
 } from '../../..';
 import {api} from '@loopback/openapi-v2';
 import {Application} from '@loopback/core';
@@ -36,7 +37,7 @@ describe('Sequence', () => {
   let server: RestServer;
   beforeEach(givenAppWithController);
   it('provides a default sequence', async () => {
-    whenIMakeRequestTo(app)
+    whenIRequest()
       .get('/name')
       .expect('SequenceApp');
   });
@@ -45,7 +46,7 @@ describe('Sequence', () => {
     server.handler((sequence, request, response) => {
       sequence.send(response, 'hello world');
     });
-    return whenIMakeRequestTo(app)
+    return whenIRequest()
       .get('/')
       .expect('hello world');
   });
@@ -61,7 +62,7 @@ describe('Sequence', () => {
     // bind user defined sequence
     server.sequence(MySequence);
 
-    whenIMakeRequestTo(app)
+    whenIRequest()
       .get('/')
       .expect('hello world');
   });
@@ -86,19 +87,37 @@ describe('Sequence', () => {
 
     server.sequence(MySequence);
 
-    return whenIMakeRequestTo(app)
+    return whenIRequest()
       .get('/name')
       .expect('MySequence SequenceApp');
   });
 
+  it('allows users to bind a custom sequence class via app.sequence()', async () => {
+    class MySequence {
+      constructor(@inject(SequenceActions.SEND) protected send: Send) {}
+
+      async handle(req: ParsedRequest, res: ServerResponse) {
+        this.send(res, 'MySequence was invoked.');
+      }
+    }
+
+    const restApp = new RestApplication();
+    restApp.sequence(MySequence);
+
+    const appServer = await restApp.getServer(RestServer);
+    await whenIRequest(appServer)
+      .get('/name')
+      .expect('MySequence was invoked.');
+  });
+
   it('user-defined Send', () => {
     const send: Send = (response, result) => {
       response.setHeader('content-type', 'text/plain');
       response.end(`CUSTOM FORMAT: ${result}`);
     };
     server.bind(SequenceActions.SEND).to(send);
 
-    return whenIMakeRequestTo(app)
+    return whenIRequest()
       .get('/name')
       .expect('CUSTOM FORMAT: SequenceApp');
   });
@@ -110,7 +129,7 @@ describe('Sequence', () => {
     };
     server.bind(SequenceActions.REJECT).to(reject);
 
-    return whenIMakeRequestTo(app)
+    return whenIRequest()
       .get('/unknown-url')
       .expect(418);
   });
@@ -122,7 +141,7 @@ describe('Sequence', () => {
       sequence.send(response, sequence.ctx.getSync('test'));
     });
 
-    return whenIMakeRequestTo(app)
+    return whenIRequest()
       .get('/')
       .expect('hello world');
   });
@@ -149,7 +168,7 @@ describe('Sequence', () => {
     server.sequence(MySequence);
     app.bind('test').to('hello world');
 
-    return whenIMakeRequestTo(app)
+    return whenIRequest()
       .get('/')
       .expect('hello world');
   });
@@ -194,7 +213,7 @@ describe('Sequence', () => {
     app.controller(controller);
   }
 
-  function whenIMakeRequestTo(application: Application): Client {
-    return createClientForHandler(server.handleHttp);
+  function whenIRequest(restServer: RestServer = server): Client {
+    return createClientForHandler(restServer.handleHttp);
   }
 });