@loopback/rest 4.0.0-alpha.8 → 5.0.1

package/src/rest.server.ts

@@ -0,0 +1,1192 @@
+// Copyright IBM Corp. 2018,2020. All Rights Reserved.
+// Node module: @loopback/rest
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import {
+  Binding,
+  BindingAddress,
+  BindingScope,
+  Constructor,
+  ContextObserver,
+  createBindingFromClass,
+  filterByKey,
+  filterByTag,
+  inject,
+  Subscription,
+} from '@loopback/context';
+import {Application, CoreBindings, Server} from '@loopback/core';
+import {BaseMiddlewareRegistry, ExpressRequestHandler} from '@loopback/express';
+import {HttpServer, HttpServerOptions} from '@loopback/http-server';
+import {
+  getControllerSpec,
+  OASEnhancerBindings,
+  OASEnhancerService,
+  OpenAPIObject,
+  OpenApiSpec,
+  OperationObject,
+  ServerObject,
+} from '@loopback/openapi-v3';
+import assert, {AssertionError} from 'assert';
+import cors from 'cors';
+import debugFactory from 'debug';
+import express, {ErrorRequestHandler} from 'express';
+import {PathParams} from 'express-serve-static-core';
+import {IncomingMessage, ServerResponse} from 'http';
+import {ServerOptions} from 'https';
+import {safeDump} from 'js-yaml';
+import {cloneDeep} from 'lodash';
+import {ServeStaticOptions} from 'serve-static';
+import {writeErrorToResponse} from 'strong-error-handler';
+import {BodyParser, REQUEST_BODY_PARSER_TAG} from './body-parsers';
+import {HttpHandler} from './http-handler';
+import {RestBindings, RestTags} from './keys';
+import {RequestContext} from './request-context';
+import {
+  ControllerClass,
+  ControllerFactory,
+  ControllerInstance,
+  ControllerRoute,
+  createControllerFactoryForBinding,
+  createRoutesForController,
+  ExternalExpressRoutes,
+  RedirectRoute,
+  RestRouterOptions,
+  Route,
+  RouteEntry,
+  RouterSpec,
+  RoutingTable,
+} from './router';
+import {assignRouterSpec} from './router/router-spec';
+import {DefaultSequence, SequenceFunction, SequenceHandler} from './sequence';
+import {Request, RequestBodyParserOptions, Response} from './types';
+
+const debug = debugFactory('loopback:rest:server');
+
+export type HttpRequestListener = (
+  req: IncomingMessage,
+  res: ServerResponse,
+) => void;
+
+export interface HttpServerLike {
+  requestHandler: HttpRequestListener;
+}
+
+const SequenceActions = RestBindings.SequenceActions;
+
+/**
+ * A REST API server for use with Loopback.
+ * Add this server to your application by importing the RestComponent.
+ *
+ * @example
+ * ```ts
+ * const app = new MyApplication();
+ * app.component(RestComponent);
+ * ```
+ *
+ * To add additional instances of RestServer to your application, use the
+ * `.server` function:
+ * ```ts
+ * app.server(RestServer, 'nameOfYourServer');
+ * ```
+ *
+ * By default, one instance of RestServer will be created when the RestComponent
+ * is bootstrapped. This instance can be retrieved with
+ * `app.getServer(RestServer)`, or by calling `app.get('servers.RestServer')`
+ * Note that retrieving other instances of RestServer must be done using the
+ * server's name:
+ * ```ts
+ * const server = await app.getServer('foo')
+ * // OR
+ * const server = await app.get('servers.foo');
+ * ```
+ */
+export class RestServer extends BaseMiddlewareRegistry
+  implements Server, HttpServerLike {
+  /**
+   * Handle incoming HTTP(S) request by invoking the corresponding
+   * Controller method via the configured Sequence.
+   *
+   * @example
+   *
+   * ```ts
+   * const app = new Application();
+   * app.component(RestComponent);
+   * // setup controllers, etc.
+   *
+   * const restServer = await app.getServer(RestServer);
+   * const httpServer = http.createServer(restServer.requestHandler);
+   * httpServer.listen(3000);
+   * ```
+   *
+   * @param req - The request.
+   * @param res - The response.
+   */
+
+  protected _OASEnhancer: OASEnhancerService;
+  public get OASEnhancer(): OASEnhancerService {
+    this._setupOASEnhancerIfNeeded();
+    return this._OASEnhancer;
+  }
+
+  protected _requestHandler: HttpRequestListener;
+  public get requestHandler(): HttpRequestListener {
+    if (this._requestHandler == null) {
+      this._setupRequestHandlerIfNeeded();
+    }
+    return this._requestHandler;
+  }
+
+  public readonly config: RestServerResolvedConfig;
+  private _basePath: string;
+
+  protected _httpHandler: HttpHandler;
+  protected get httpHandler(): HttpHandler {
+    this._setupHandlerIfNeeded();
+    return this._httpHandler;
+  }
+
+  /**
+   * Context event subscriptions for route related changes
+   */
+  private _routesEventSubscription: Subscription;
+
+  protected _httpServer: HttpServer | undefined;
+
+  protected _expressApp?: express.Application;
+
+  get listening(): boolean {
+    return this._httpServer ? this._httpServer.listening : false;
+  }
+
+  /**
+   * The base url for the server, including the basePath if set. For example,
+   * the value will be 'http://localhost:3000/api' if `basePath` is set to
+   * '/api'.
+   */
+  get url(): string | undefined {
+    let serverUrl = this.rootUrl;
+    if (!serverUrl) return serverUrl;
+    serverUrl = serverUrl + (this._basePath || '');
+    return serverUrl;
+  }
+
+  /**
+   * The root url for the server without the basePath. For example, the value
+   * will be 'http://localhost:3000' regardless of the `basePath`.
+   */
+  get rootUrl(): string | undefined {
+    return this._httpServer && this._httpServer.url;
+  }
+
+  /**
+   *
+   * Creates an instance of RestServer.
+   *
+   * @param app - The application instance (injected via
+   * CoreBindings.APPLICATION_INSTANCE).
+   * @param config - The configuration options (injected via
+   * RestBindings.CONFIG).
+   *
+   */
+  constructor(
+    @inject(CoreBindings.APPLICATION_INSTANCE) app: Application,
+    @inject(RestBindings.CONFIG, {optional: true})
+    config: RestServerConfig = {},
+  ) {
+    super(app);
+
+    this.config = resolveRestServerConfig(config);
+
+    this.bind(RestBindings.PORT).to(this.config.port);
+    this.bind(RestBindings.HOST).to(config.host);
+    this.bind(RestBindings.PATH).to(config.path);
+    this.bind(RestBindings.PROTOCOL).to(config.protocol ?? 'http');
+    this.bind(RestBindings.HTTPS_OPTIONS).to(config as ServerOptions);
+
+    if (config.requestBodyParser) {
+      this.bind(RestBindings.REQUEST_BODY_PARSER_OPTIONS).to(
+        config.requestBodyParser,
+      );
+    }
+
+    if (config.sequence) {
+      this.sequence(config.sequence);
+    }
+
+    if (config.router) {
+      this.bind(RestBindings.ROUTER_OPTIONS).to(config.router);
+    }
+
+    this.basePath(config.basePath);
+
+    this.bind(RestBindings.BASE_PATH).toDynamicValue(() => this._basePath);
+    this.bind(RestBindings.HANDLER).toDynamicValue(() => this.httpHandler);
+  }
+
+  protected _setupOASEnhancerIfNeeded() {
+    if (this._OASEnhancer != null) return;
+    this.add(
+      createBindingFromClass(OASEnhancerService, {
+        key: OASEnhancerBindings.OAS_ENHANCER_SERVICE,
+      }),
+    );
+    this._OASEnhancer = this.getSync(OASEnhancerBindings.OAS_ENHANCER_SERVICE);
+  }
+
+  protected _setupRequestHandlerIfNeeded() {
+    if (this._expressApp != null) return;
+    this._expressApp = express();
+    this._applyExpressSettings();
+    this._requestHandler = this._expressApp;
+
+    // Allow CORS support for all endpoints so that users
+    // can test with online SwaggerUI instance
+    this.expressMiddleware(cors, this.config.cors, {
+      injectConfiguration: false,
+      key: 'middleware.cors',
+      group: 'cors',
+    });
+
+    // Set up endpoints for OpenAPI spec/ui
+    this._setupOpenApiSpecEndpoints();
+
+    // Mount our router & request handler
+    this._expressApp.use(this._basePath, (req, res, next) => {
+      this._handleHttpRequest(req, res).catch(next);
+    });
+
+    // Mount our error handler
+    this._expressApp.use(this._unexpectedErrorHandler());
+  }
+
+  /**
+   * Get an Express handler for unexpected errors
+   */
+  protected _unexpectedErrorHandler(): ErrorRequestHandler {
+    const handleUnExpectedError: ErrorRequestHandler = (
+      err,
+      req,
+      res,
+      next,
+    ) => {
+      // Handle errors reported by Express middleware such as CORS
+      // First try to use the `REJECT` action
+      this.get(SequenceActions.REJECT, {optional: true})
+        .then(reject => {
+          if (reject) {
+            // TODO(rfeng): There is a possibility that the error is thrown
+            // from the `REJECT` action in the sequence
+            return reject({request: req, response: res}, err);
+          }
+          // Use strong-error handler directly
+          writeErrorToResponse(err, req, res);
+        })
+        .catch(unexpectedErr => next(unexpectedErr));
+    };
+    return handleUnExpectedError;
+  }
+
+  /**
+   * Apply express settings.
+   */
+  protected _applyExpressSettings() {
+    assertExists(this._expressApp, 'this._expressApp');
+    const settings = this.config.expressSettings;
+    for (const key in settings) {
+      this._expressApp.set(key, settings[key]);
+    }
+    if (this.config.router && typeof this.config.router.strict === 'boolean') {
+      this._expressApp.set('strict routing', this.config.router.strict);
+    }
+  }
+
+  /**
+   * Mount /openapi.json, /openapi.yaml for specs and /swagger-ui, /explorer
+   * to redirect to externally hosted API explorer
+   */
+  protected _setupOpenApiSpecEndpoints() {
+    assertExists(this._expressApp, 'this._expressApp');
+    if (this.config.openApiSpec.disabled) return;
+    const router = express.Router();
+    const mapping = this.config.openApiSpec.endpointMapping!;
+    // Serving OpenAPI spec
+    for (const p in mapping) {
+      this.addOpenApiSpecEndpoint(p, mapping[p], router);
+    }
+    const explorerPaths = ['/swagger-ui', '/explorer'];
+    router.get(explorerPaths, (req, res, next) =>
+      this._redirectToSwaggerUI(req, res, next),
+    );
+    this.expressMiddleware('middleware.apiSpec.defaults', router, {
+      group: 'apiSpec',
+    });
+  }
+
+  /**
+   * Add a new non-controller endpoint hosting a form of the OpenAPI spec.
+   *
+   * @param path Path at which to host the copy of the OpenAPI
+   * @param form Form that should be rendered from that path
+   */
+  addOpenApiSpecEndpoint(
+    path: string,
+    form: OpenApiSpecForm,
+    router?: express.Router,
+  ) {
+    if (router == null) {
+      const key = `middleware.apiSpec.${path}.${form}`;
+      if (this.contains(key)) {
+        throw new Error(
+          `The path ${path} is already configured for OpenApi hosting`,
+        );
+      }
+      const newRouter = express.Router();
+      newRouter.get(path, (req, res) => this._serveOpenApiSpec(req, res, form));
+      this.expressMiddleware(
+        () => newRouter,
+        {},
+        {
+          injectConfiguration: false,
+          key: `middleware.apiSpec.${path}.${form}`,
+          group: 'apiSpec',
+        },
+      );
+    } else {
+      router.get(path, (req, res) => this._serveOpenApiSpec(req, res, form));
+    }
+  }
+
+  protected _handleHttpRequest(request: Request, response: Response) {
+    return this.httpHandler.handleRequest(request, response);
+  }
+
+  protected _setupHandlerIfNeeded() {
+    if (this._httpHandler) return;
+
+    // Watch for binding events
+    // See https://github.com/strongloop/loopback-next/issues/433
+    const routesObserver: ContextObserver = {
+      filter: binding =>
+        filterByKey(RestBindings.API_SPEC.key)(binding) ||
+        (filterByKey(/^(controllers|routes)\..+/)(binding) &&
+          // Exclude controller routes to avoid circular events
+          !filterByTag(RestTags.CONTROLLER_ROUTE)(binding)),
+      observe: () => {
+        // Rebuild the HttpHandler instance whenever a controller/route was
+        // added/deleted.
+        this._createHttpHandler();
+      },
+    };
+    this._routesEventSubscription = this.subscribe(routesObserver);
+
+    this._createHttpHandler();
+  }
+
+  /**
+   * Create an instance of HttpHandler and populates it with routes
+   */
+  private _createHttpHandler() {
+    /**
+     * Check if there is custom router in the context
+     */
+    const router = this.getSync(RestBindings.ROUTER, {optional: true});
+    const routingTable = new RoutingTable(router, this._externalRoutes);
+
+    this._httpHandler = new HttpHandler(this, this.config, routingTable);
+
+    // Remove controller routes
+    for (const b of this.findByTag(RestTags.CONTROLLER_ROUTE)) {
+      this.unbind(b.key);
+    }
+
+    for (const b of this.find(`${CoreBindings.CONTROLLERS}.*`)) {
+      const controllerName = b.key.replace(/^controllers\./, '');
+      const ctor = b.valueConstructor;
+      if (!ctor) {
+        throw new Error(
+          `The controller ${controllerName} was not bound via .toClass()`,
+        );
+      }
+      const apiSpec = getControllerSpec(ctor);
+      if (!apiSpec) {
+        // controller methods are specified through app.api() spec
+        debug('Skipping controller %s - no API spec provided', controllerName);
+        continue;
+      }
+
+      debug('Registering controller %s', controllerName);
+      if (apiSpec.components) {
+        this._httpHandler.registerApiComponents(apiSpec.components);
+      }
+      const controllerFactory = createControllerFactoryForBinding(b.key);
+      const routes = createRoutesForController(
+        apiSpec,
+        ctor,
+        controllerFactory,
+      );
+      for (const route of routes) {
+        const binding = this.bindRoute(route);
+        binding
+          .tag(RestTags.CONTROLLER_ROUTE)
+          .tag({[RestTags.CONTROLLER_BINDING]: b.key});
+      }
+    }
+
+    for (const b of this.findByTag(RestTags.REST_ROUTE)) {
+      // TODO(bajtos) should we support routes defined asynchronously?
+      const route = this.getSync<RouteEntry>(b.key);
+      this._httpHandler.registerRoute(route);
+    }
+
+    // TODO(bajtos) should we support API spec defined asynchronously?
+    const spec: OpenApiSpec = this.getSync(RestBindings.API_SPEC);
+    for (const path in spec.paths) {
+      for (const verb in spec.paths[path]) {
+        const routeSpec: OperationObject = spec.paths[path][verb];
+        this._setupOperation(verb, path, routeSpec);
+      }
+    }
+  }
+
+  private _setupOperation(verb: string, path: string, spec: OperationObject) {
+    const handler = spec['x-operation'];
+    if (typeof handler === 'function') {
+      // Remove a field value that cannot be represented in JSON.
+      // Start by creating a shallow-copy of the spec, so that we don't
+      // modify the original spec object provided by user.
+      spec = Object.assign({}, spec);
+      delete spec['x-operation'];
+
+      const route = new Route(verb, path, spec, handler);
+      this._httpHandler.registerRoute(route);
+      return;
+    }
+
+    const controllerName = spec['x-controller-name'];
+    if (typeof controllerName === 'string') {
+      const b = this.getBinding(`controllers.${controllerName}`, {
+        optional: true,
+      });
+      if (!b) {
+        throw new Error(
+          `Unknown controller ${controllerName} used by "${verb} ${path}"`,
+        );
+      }
+
+      const ctor = b.valueConstructor;
+      if (!ctor) {
+        throw new Error(
+          `The controller ${controllerName} was not bound via .toClass()`,
+        );
+      }
+
+      const controllerFactory = createControllerFactoryForBinding(b.key);
+      const route = new ControllerRoute(
+        verb,
+        path,
+        spec,
+        ctor,
+        controllerFactory,
+      );
+      this._httpHandler.registerRoute(route);
+      return;
+    }
+
+    throw new Error(
+      `There is no handler configured for operation "${verb} ${path}`,
+    );
+  }
+
+  private async _serveOpenApiSpec(
+    request: Request,
+    response: Response,
+    specForm?: OpenApiSpecForm,
+  ) {
+    const requestContext = new RequestContext(
+      request,
+      response,
+      this,
+      this.config,
+    );
+
+    specForm = specForm ?? {version: '3.0.0', format: 'json'};
+    const specObj = await this.getApiSpec(requestContext);
+
+    if (specForm.format === 'json') {
+      const spec = JSON.stringify(specObj, null, 2);
+      response.setHeader('content-type', 'application/json; charset=utf-8');
+      response.end(spec, 'utf-8');
+    } else {
+      const yaml = safeDump(specObj, {});
+      response.setHeader('content-type', 'text/yaml; charset=utf-8');
+      response.end(yaml, 'utf-8');
+    }
+  }
+  private async _redirectToSwaggerUI(
+    request: Request,
+    response: Response,
+    next: express.NextFunction,
+  ) {
+    const config = this.config.apiExplorer;
+
+    if (config.disabled) {
+      debug('Redirect to swagger-ui was disabled by configuration.');
+      next();
+      return;
+    }
+
+    debug('Redirecting to swagger-ui from %j.', request.originalUrl);
+    const requestContext = new RequestContext(
+      request,
+      response,
+      this,
+      this.config,
+    );
+    const protocol = requestContext.requestedProtocol;
+    const baseUrl = protocol === 'http' ? config.httpUrl : config.url;
+    const openApiUrl = `${requestContext.requestedBaseUrl}/openapi.json`;
+    const fullUrl = `${baseUrl}?url=${openApiUrl}`;
+    response.redirect(302, fullUrl);
+  }
+
+  /**
+   * Register a controller class with this server.
+   *
+   * @param controllerCtor - The controller class
+   * (constructor function).
+   * @returns The newly created binding, you can use the reference to
+   * further modify the binding, e.g. lock the value to prevent further
+   * modifications.
+   *
+   * @example
+   * ```ts
+   * class MyController {
+   * }
+   * app.controller(MyController).lock();
+   * ```
+   *
+   */
+  controller(controllerCtor: ControllerClass<ControllerInstance>): Binding {
+    return this.bind('controllers.' + controllerCtor.name).toClass(
+      controllerCtor,
+    );
+  }
+
+  /**
+   * Register a new Controller-based route.
+   *
+   * @example
+   * ```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 controllerCtor - Controller constructor
+   * @param controllerFactory - A factory function to create controller instance
+   * @param methodName - The name of the controller method
+   */
+  route<I>(
+    verb: string,
+    path: string,
+    spec: OperationObject,
+    controllerCtor: ControllerClass<I>,
+    controllerFactory: ControllerFactory<I>,
+    methodName: string,
+  ): Binding;
+
+  /**
+   * Register a new route invoking a handler function.
+   *
+   * @example
+   * ```ts
+   * function greet(name: string) {
+   *  return `hello ${name}`;
+   * }
+   * app.route('get', '/', operationSpec, 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 handler - The function to invoke with the request parameters
+   * described in the spec.
+   */
+  route(
+    verb: string,
+    path: string,
+    spec: OperationObject,
+    handler: Function,
+  ): Binding;
+
+  /**
+   * Register a new generic route.
+   *
+   * @example
+   * ```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<T>(
+    routeOrVerb: RouteEntry | string,
+    path?: string,
+    spec?: OperationObject,
+    controllerCtorOrHandler?: ControllerClass<T> | Function,
+    controllerFactory?: ControllerFactory<T>,
+    methodName?: string,
+  ): Binding {
+    if (typeof routeOrVerb === 'object') {
+      const r = routeOrVerb;
+      // Encode the path to escape special chars
+      return this.bindRoute(r);
+    }
+
+    if (!path) {
+      throw new AssertionError({
+        message: 'path is required for a controller-based route',
+      });
+    }
+
+    if (!spec) {
+      throw new AssertionError({
+        message: 'spec is required for a controller-based route',
+      });
+    }
+
+    if (arguments.length === 4) {
+      if (!controllerCtorOrHandler) {
+        throw new AssertionError({
+          message: 'handler function is required for a handler-based route',
+        });
+      }
+      return this.route(
+        new Route(routeOrVerb, path, spec, controllerCtorOrHandler as Function),
+      );
+    }
+
+    if (!controllerCtorOrHandler) {
+      throw new AssertionError({
+        message: 'controller is required for a controller-based route',
+      });
+    }
+
+    if (!methodName) {
+      throw new AssertionError({
+        message: 'methodName is required for a controller-based route',
+      });
+    }
+
+    return this.route(
+      new ControllerRoute(
+        routeOrVerb,
+        path,
+        spec,
+        controllerCtorOrHandler as ControllerClass<T>,
+        controllerFactory,
+        methodName,
+      ),
+    );
+  }
+
+  private bindRoute(r: RouteEntry) {
+    const namespace = RestBindings.ROUTES;
+    const encodedPath = encodeURIComponent(r.path).replace(/\./g, '%2E');
+    return this.bind(`${namespace}.${r.verb} ${encodedPath}`)
+      .to(r)
+      .tag(RestTags.REST_ROUTE)
+      .tag({[RestTags.ROUTE_VERB]: r.verb, [RestTags.ROUTE_PATH]: r.path});
+  }
+
+  /**
+   * Register a route redirecting callers to a different URL.
+   *
+   * @example
+   * ```ts
+   * server.redirect('/explorer', '/explorer/');
+   * ```
+   *
+   * @param fromPath - URL path of the redirect endpoint
+   * @param toPathOrUrl - Location (URL path or full URL) where to redirect to.
+   * If your server is configured with a custom `basePath`, then the base path
+   * is prepended to the target location.
+   * @param statusCode - HTTP status code to respond with,
+   *   defaults to 303 (See Other).
+   */
+  redirect(
+    fromPath: string,
+    toPathOrUrl: string,
+    statusCode?: number,
+  ): Binding {
+    return this.route(
+      new RedirectRoute(fromPath, this._basePath + toPathOrUrl, statusCode),
+    );
+  }
+
+  /*
+   * Registry of external routes & static assets
+   */
+  private _externalRoutes = new ExternalExpressRoutes();
+
+  /**
+   * Mount static assets to the REST server.
+   * See https://expressjs.com/en/4x/api.html#express.static
+   * @param path - The path(s) to serve the asset.
+   * See examples at https://expressjs.com/en/4x/api.html#path-examples
+   * @param rootDir - The root directory from which to serve static assets
+   * @param options - Options for serve-static
+   */
+  static(path: PathParams, rootDir: string, options?: ServeStaticOptions) {
+    this._externalRoutes.registerAssets(path, rootDir, options);
+  }
+
+  /**
+   * Set the OpenAPI specification that defines the REST API schema for this
+   * server. 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 spec - The OpenAPI specification, as an object.
+   * @returns Binding for the spec
+   *
+   */
+  api(spec: OpenApiSpec): Binding {
+    return this.bind(RestBindings.API_SPEC).to(spec);
+  }
+
+  /**
+   * Get the OpenAPI specification describing the REST API provided by
+   * this application.
+   *
+   * This method merges operations (HTTP endpoints) from the following sources:
+   *  - `app.api(spec)`
+   *  - `app.controller(MyController)`
+   *  - `app.route(route)`
+   *  - `app.route('get', '/greet', operationSpec, MyController, 'greet')`
+   *
+   * If the optional `requestContext` is provided, then the `servers` list
+   * in the returned spec will be updated to work in that context.
+   * Specifically:
+   * 1. if `config.openApi.setServersFromRequest` is enabled, the servers
+   * list will be replaced with the context base url
+   * 2. Any `servers` entries with a path of `/` will have that path
+   * replaced with `requestContext.basePath`
+   *
+   * @param requestContext - Optional context to update the `servers` list
+   * in the returned spec
+   */
+  async getApiSpec(requestContext?: RequestContext): Promise<OpenApiSpec> {
+    let spec = await this.get<OpenApiSpec>(RestBindings.API_SPEC);
+    const components = this.httpHandler.getApiComponents();
+
+    // Apply deep clone to prevent getApiSpec() callers from
+    // accidentally modifying our internal routing data
+    spec.paths = cloneDeep(this.httpHandler.describeApiPaths());
+    if (components) {
+      const defs = cloneDeep(components);
+      spec.components = {...spec.components, ...defs};
+    }
+
+    assignRouterSpec(spec, this._externalRoutes.routerSpec);
+
+    if (requestContext) {
+      spec = this.updateSpecFromRequest(spec, requestContext);
+    }
+
+    // Apply OAS enhancers to the OpenAPI specification
+    this.OASEnhancer.spec = spec;
+    spec = await this.OASEnhancer.applyAllEnhancers();
+
+    return spec;
+  }
+
+  /**
+   * Update or rebuild OpenAPI Spec object to be appropriate for the context of
+   * a specific request for the spec, leveraging both app config and request
+   * path information.
+   *
+   * @param spec base spec object from which to start
+   * @param requestContext request to use to infer path information
+   * @returns Updated or rebuilt spec object to use in the context of the request
+   */
+  private updateSpecFromRequest(
+    spec: OpenAPIObject,
+    requestContext: RequestContext,
+  ) {
+    if (this.config.openApiSpec.setServersFromRequest) {
+      spec = Object.assign({}, spec);
+      spec.servers = [{url: requestContext.requestedBaseUrl}];
+    }
+
+    const basePath = requestContext.basePath;
+    if (spec.servers && basePath) {
+      for (const s of spec.servers) {
+        // Update the default server url to honor `basePath`
+        if (s.url === '/') {
+          s.url = basePath;
+        }
+      }
+    }
+
+    return spec;
+  }
+
+  /**
+   * Configure a custom sequence class for handling incoming requests.
+   *
+   * @example
+   * ```ts
+   * class MySequence implements SequenceHandler {
+   *   constructor(
+   *     @inject('send) public send: Send)) {
+   *   }
+   *
+   *   public async handle({response}: RequestContext) {
+   *     send(response, 'hello world');
+   *   }
+   * }
+   * ```
+   *
+   * @param value - The sequence to invoke for each incoming request.
+   */
+  public sequence(value: Constructor<SequenceHandler>) {
+    this.bind(RestBindings.SEQUENCE).toClass(value);
+  }
+
+  /**
+   * Configure a custom sequence function for handling incoming requests.
+   *
+   * @example
+   * ```ts
+   * app.handler(({request, response}, sequence) => {
+   *   sequence.send(response, 'hello world');
+   * });
+   * ```
+   *
+   * @param handlerFn - The handler to invoke for each incoming request.
+   */
+  public handler(handlerFn: SequenceFunction) {
+    class SequenceFromFunction extends DefaultSequence {
+      async handle(context: RequestContext): Promise<void> {
+        return handlerFn(context, this);
+      }
+    }
+
+    this.sequence(SequenceFromFunction);
+  }
+
+  /**
+   * Bind a body parser to the server context
+   * @param parserClass - Body parser class
+   * @param address - Optional binding address
+   */
+  bodyParser(
+    bodyParserClass: Constructor<BodyParser>,
+    address?: BindingAddress<BodyParser>,
+  ): Binding<BodyParser> {
+    const binding = createBodyParserBinding(bodyParserClass, address);
+    this.add(binding);
+    return binding;
+  }
+
+  /**
+   * Configure the `basePath` for the rest server
+   * @param path - Base path
+   */
+  basePath(path = '') {
+    if (this._requestHandler != null) {
+      throw new Error(
+        'Base path cannot be set as the request handler has been created',
+      );
+    }
+    // Trim leading and trailing `/`
+    path = path.replace(/(^\/)|(\/$)/, '');
+    if (path) path = '/' + path;
+    this._basePath = path;
+    this.config.basePath = path;
+  }
+
+  /**
+   * Start this REST API's HTTP/HTTPS server.
+   */
+  async start(): Promise<void> {
+    // Set up the Express app if not done yet
+    this._setupRequestHandlerIfNeeded();
+    // Setup the HTTP handler so that we can verify the configuration
+    // of API spec, controllers and routes at startup time.
+    this._setupHandlerIfNeeded();
+
+    const port = await this.get(RestBindings.PORT);
+    const host = await this.get(RestBindings.HOST);
+    const path = await this.get(RestBindings.PATH);
+    const protocol = await this.get(RestBindings.PROTOCOL);
+    const httpsOptions = await this.get(RestBindings.HTTPS_OPTIONS);
+
+    if (this.config.listenOnStart === false) {
+      debug(
+        'RestServer is not listening as listenOnStart flag is set to false.',
+      );
+      return;
+    }
+
+    const serverOptions = {};
+    if (protocol === 'https') Object.assign(serverOptions, httpsOptions);
+    Object.assign(serverOptions, {port, host, protocol, path});
+
+    this._httpServer = new HttpServer(this.requestHandler, serverOptions);
+
+    await this._httpServer.start();
+
+    this.bind(RestBindings.PORT).to(this._httpServer.port);
+    this.bind(RestBindings.HOST).to(this._httpServer.host);
+    this.bind(RestBindings.URL).to(this._httpServer.url);
+    debug('RestServer listening at %s', this._httpServer.url);
+  }
+
+  /**
+   * Stop this REST API's HTTP/HTTPS server.
+   */
+  async stop() {
+    // Kill the server instance.
+    if (!this._httpServer) return;
+    await this._httpServer.stop();
+    this._httpServer = undefined;
+  }
+
+  /**
+   * Mount an Express router to expose additional REST endpoints handled
+   * via legacy Express-based stack.
+   *
+   * @param basePath - Path where to mount the router at, e.g. `/` or `/api`.
+   * @param router - The Express router to handle the requests.
+   * @param spec - A partial OpenAPI spec describing endpoints provided by the
+   * router. LoopBack will prepend `basePath` to all endpoints automatically.
+   * This argument is optional. You can leave it out if you don't want to
+   * document the routes.
+   */
+  mountExpressRouter(
+    basePath: string,
+    router: ExpressRequestHandler,
+    spec?: RouterSpec,
+  ): void {
+    this._externalRoutes.mountRouter(basePath, router, spec);
+  }
+}
+
+/**
+ * An assertion type guard for TypeScript to instruct the compiler that the
+ * given value is not `null` or `undefined.
+ * @param val - A value can be `undefined` or `null`
+ * @param name - Name of the value
+ */
+function assertExists<T>(val: T, name: string): asserts val is NonNullable<T> {
+  assert(val != null, `The value of ${name} cannot be null or undefined`);
+}
+
+/**
+ * Create a binding for the given body parser class
+ * @param parserClass - Body parser class
+ * @param key - Optional binding address
+ */
+export function createBodyParserBinding(
+  parserClass: Constructor<BodyParser>,
+  key?: BindingAddress<BodyParser>,
+): Binding<BodyParser> {
+  const address =
+    key ?? `${RestBindings.REQUEST_BODY_PARSER}.${parserClass.name}`;
+  return Binding.bind<BodyParser>(address)
+    .toClass(parserClass)
+    .inScope(BindingScope.TRANSIENT)
+    .tag(REQUEST_BODY_PARSER_TAG);
+}
+
+/**
+ * The form of OpenAPI specs to be served
+ */
+export interface OpenApiSpecForm {
+  version?: string;
+  format?: string;
+}
+
+const OPENAPI_SPEC_MAPPING: {[key: string]: OpenApiSpecForm} = {
+  '/openapi.json': {version: '3.0.0', format: 'json'},
+  '/openapi.yaml': {version: '3.0.0', format: 'yaml'},
+};
+
+/**
+ * Options to customize how OpenAPI specs are served
+ */
+export interface OpenApiSpecOptions {
+  /**
+   * Mapping of urls to spec forms, by default:
+   * ```
+   * {
+   *   '/openapi.json': {version: '3.0.0', format: 'json'},
+   *   '/openapi.yaml': {version: '3.0.0', format: 'yaml'},
+   * }
+   * ```
+   */
+  endpointMapping?: {[key: string]: OpenApiSpecForm};
+
+  /**
+   * A flag to force `servers` to be set from the http request for the OpenAPI
+   * spec
+   */
+  setServersFromRequest?: boolean;
+
+  /**
+   * Configure servers for OpenAPI spec
+   */
+  servers?: ServerObject[];
+  /**
+   * Set this flag to disable the endpoint for OpenAPI spec
+   */
+  disabled?: true;
+
+  /**
+   * Set this flag to `false` to disable OAS schema consolidation. If not set,
+   * the value defaults to `true`.
+   */
+  consolidate?: boolean;
+}
+
+export interface ApiExplorerOptions {
+  /**
+   * URL for the hosted API explorer UI
+   * default to https://loopback.io/api-explorer
+   */
+  url?: string;
+
+  /**
+   * URL for the API explorer served over `http` protocol to deal with mixed
+   * content security imposed by browsers as the spec is exposed over `http` by
+   * default.
+   * See https://github.com/strongloop/loopback-next/issues/1603
+   */
+  httpUrl?: string;
+
+  /**
+   * Set this flag to disable the built-in redirect to externally
+   * hosted API Explorer UI.
+   */
+  disabled?: true;
+}
+
+/**
+ * RestServer options
+ */
+export type RestServerOptions = Partial<RestServerResolvedOptions>;
+
+export interface RestServerResolvedOptions {
+  port: number;
+  path?: string;
+
+  /**
+   * Base path for API/static routes
+   */
+  basePath?: string;
+  cors: cors.CorsOptions;
+  openApiSpec: OpenApiSpecOptions;
+  apiExplorer: ApiExplorerOptions;
+  requestBodyParser?: RequestBodyParserOptions;
+  sequence?: Constructor<SequenceHandler>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  expressSettings: {[name: string]: any};
+  router: RestRouterOptions;
+
+  /**
+   * Set this flag to `false` to not listen on connections when the REST server
+   * is started. It's useful to mount a LoopBack REST server as a route to the
+   * facade Express application. If not set, the value is default to `true`.
+   */
+  listenOnStart?: boolean;
+}
+
+/**
+ * Valid configuration for the RestServer constructor.
+ */
+export type RestServerConfig = RestServerOptions & HttpServerOptions;
+
+export type RestServerResolvedConfig = RestServerResolvedOptions &
+  HttpServerOptions;
+
+const DEFAULT_CONFIG: RestServerResolvedConfig = {
+  port: 3000,
+  openApiSpec: {},
+  apiExplorer: {},
+  cors: {
+    origin: '*',
+    methods: 'GET,HEAD,PUT,PATCH,POST,DELETE',
+    preflightContinue: false,
+    optionsSuccessStatus: 204,
+    maxAge: 86400,
+    credentials: true,
+  },
+  expressSettings: {},
+  router: {},
+  listenOnStart: true,
+};
+
+function resolveRestServerConfig(
+  config: RestServerConfig,
+): RestServerResolvedConfig {
+  const result: RestServerResolvedConfig = Object.assign(
+    cloneDeep(DEFAULT_CONFIG),
+    config,
+  );
+
+  // Can't check falsiness, 0 is a valid port.
+  if (result.port == null) {
+    result.port = 3000;
+  }
+
+  if (result.host == null) {
+    // Set it to '' so that the http server will listen on all interfaces
+    result.host = undefined;
+  }
+
+  if (!result.openApiSpec.endpointMapping) {
+    // mapping may be mutated by addOpenApiSpecEndpoint, be sure that doesn't
+    // pollute the default mapping configuration
+    result.openApiSpec.endpointMapping = cloneDeep(OPENAPI_SPEC_MAPPING);
+  }
+
+  result.apiExplorer = normalizeApiExplorerConfig(config.apiExplorer);
+
+  if (result.openApiSpec.disabled) {
+    // Disable apiExplorer if the OpenAPI spec endpoint is disabled
+    result.apiExplorer.disabled = true;
+  }
+
+  return result;
+}
+
+function normalizeApiExplorerConfig(
+  input: ApiExplorerOptions | undefined,
+): ApiExplorerOptions {
+  const config = input ?? {};
+  const url = config.url ?? 'https://explorer.loopback.io';
+
+  config.httpUrl =
+    config.httpUrl ?? config.url ?? 'http://explorer.loopback.io';
+
+  config.url = url;
+
+  return config;
+}