@loopback/openapi-v3 1.10.3 → 2.0.0

package/dist/keys.js.map

@@ -1 +1 @@
-{"version":3,"file":"keys.js","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":";AAAA,iDAAiD;AACjD,oCAAoC;AACpC,+CAA+C;AAC/C,gEAAgE;;AAEhE,+CAAmD;AAInD,iDAAiD;AACjD,oCAAoC;AACpC,+CAA+C;AAC/C,gEAAgE;AAEhE,IAAiB,QAAQ,CAwCxB;AAxCD,WAAiB,QAAQ;IACvB;;OAEG;IACU,oBAAW,GAAG,0BAAgB,CAAC,MAAM,CAGhD,oBAAoB,CAAC,CAAC;IAExB;;OAEG;IACU,uBAAc,GAAG,0BAAgB,CAAC,MAAM,CAGnD,uBAAuB,CAAC,CAAC;IAE3B;;OAEG;IACU,kBAAS,GAAG,0BAAgB,CAAC,MAAM,CAG9C,kBAAkB,CAAC,CAAC;IAEtB;;OAEG;IACU,4BAAmB,GAAG,0BAAgB,CAAC,MAAM,CAGxD,4BAA4B,CAAC,CAAC;IAEhC;;OAEG;IACU,yBAAgB,GAAG,0BAAgB,CAAC,MAAM,CAGrD,yBAAyB,CAAC,CAAC;AAC/B,CAAC,EAxCgB,QAAQ,GAAR,gBAAQ,KAAR,gBAAQ,QAwCxB"}
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":";AAAA,iDAAiD;AACjD,oCAAoC;AACpC,+CAA+C;AAC/C,gEAAgE;;AAEhE,yCAAgD;AAIhD,IAAiB,QAAQ,CAwExB;AAxED,WAAiB,QAAQ;IACvB;;OAEG;IACU,oBAAW,GAAG,uBAAgB,CAAC,MAAM,CAGhD,oBAAoB,CAAC,CAAC;IAExB;;OAEG;IACU,8BAAqB,GAAG,uBAAgB,CAAC,MAAM,CAG1D,+BAA+B,CAAC,CAAC;IAEnC;;OAEG;IACU,6BAAoB,GAAG,uBAAgB,CAAC,MAAM,CAGzD,6BAA6B,CAAC,CAAC;IAEjC;;OAEG;IACU,uBAAc,GAAG,uBAAgB,CAAC,MAAM,CAGnD,uBAAuB,CAAC,CAAC;IAE3B;;OAEG;IACU,wBAAe,GAAG,uBAAgB,CAAC,MAAM,CAGpD,yBAAyB,CAAC,CAAC;IAE7B;;OAEG;IACU,uBAAc,GAAG,uBAAgB,CAAC,MAAM,CAGnD,uBAAuB,CAAC,CAAC;IAE3B;;OAEG;IACU,kBAAS,GAAG,uBAAgB,CAAC,MAAM,CAG9C,kBAAkB,CAAC,CAAC;IAEtB;;OAEG;IACU,4BAAmB,GAAG,uBAAgB,CAAC,MAAM,CAGxD,4BAA4B,CAAC,CAAC;IAEhC;;OAEG;IACU,yBAAgB,GAAG,uBAAgB,CAAC,MAAM,CAGrD,yBAAyB,CAAC,CAAC;AAC/B,CAAC,EAxEgB,QAAQ,GAAR,gBAAQ,KAAR,gBAAQ,QAwExB"}

package/dist/types.d.ts

@@ -7,3 +7,6 @@ export * from 'openapi3-ts';
  * @deprecated Use `OpenApiBuilder` from `openapi3-ts` instead.
  */
 export declare function createEmptyApiSpec(): OpenApiSpec;
+export interface TagsDecoratorMetadata {
+    tags: string[];
+}

package/package.json

@@ -1,26 +1,27 @@
 {
   "name": "@loopback/openapi-v3",
-  "version": "1.10.3",
+  "version": "2.0.0",
   "description": "Processes openapi v3 related metadata",
   "engines": {
     "node": ">=8.9"
   },
   "dependencies": {
-    "@loopback/context": "^1.25.0",
-    "@loopback/repository-json-schema": "^1.11.3",
+    "@loopback/core": "^1.12.4",
+    "@loopback/repository-json-schema": "^1.12.2",
     "debug": "^4.1.1",
+    "json-merge-patch": "^0.2.3",
     "lodash": "^4.17.15",
     "openapi3-ts": "^1.3.0"
   },
   "devDependencies": {
-    "@loopback/build": "^3.0.0",
-    "@loopback/eslint-config": "^5.0.0",
-    "@loopback/openapi-spec-builder": "^1.2.20",
-    "@loopback/repository": "^1.16.0",
-    "@loopback/testlab": "^1.10.0",
+    "@loopback/build": "^3.1.1",
+    "@loopback/eslint-config": "^5.0.3",
+    "@loopback/openapi-spec-builder": "^1.3.1",
+    "@loopback/repository": "^1.19.1",
+    "@loopback/testlab": "^1.10.3",
     "@types/debug": "^4.1.5",
     "@types/lodash": "^4.14.149",
-    "@types/node": "^10.17.6"
+    "@types/node": "^10.17.14"
   },
   "scripts": {
     "build": "lb-tsc",
@@ -55,5 +56,5 @@
     "url": "https://github.com/strongloop/loopback-next.git",
     "directory": "packages/openapi-v3"
   },
-  "gitHead": "89eb61bacaed75e6eb61ae6840cea266cb888659"
+  "gitHead": "6eea5e428b145cafb84a998bd53979da8c8fba07"
 }

package/src/controller-spec.ts

@@ -3,13 +3,13 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import {DecoratorFactory, MetadataInspector} from '@loopback/context';
+import {DecoratorFactory, MetadataInspector} from '@loopback/core';
 import {
   getJsonSchema,
   getJsonSchemaRef,
   JsonSchemaOptions,
 } from '@loopback/repository-json-schema';
-import _ from 'lodash';
+import {includes} from 'lodash';
 import {resolveSchema} from './generate-schema';
 import {jsonToSchemaObject, SchemaRef} from './json-to-schema';
 import {OAI3Keys} from './keys';
@@ -25,6 +25,7 @@ import {
   ResponseObject,
   SchemaObject,
   SchemasObject,
+  TagsDecoratorMetadata,
 } from './types';
 
 const debug = require('debug')('loopback:openapi3:metadata:controller-spec');
@@ -77,6 +78,47 @@ function resolveControllerSpec(constructor: Function): ControllerSpec {
     spec = {paths: {}};
   }
 
+  const isClassDeprecated = MetadataInspector.getClassMetadata<boolean>(
+    OAI3Keys.DEPRECATED_CLASS_KEY,
+    constructor,
+  );
+
+  if (isClassDeprecated) {
+    debug('  using class-level @deprecated()');
+  }
+  const classTags = MetadataInspector.getClassMetadata<TagsDecoratorMetadata>(
+    OAI3Keys.TAGS_CLASS_KEY,
+    constructor,
+  );
+
+  if (classTags) {
+    debug('  using class-level @oas.tags()');
+  }
+
+  if (classTags || isClassDeprecated) {
+    for (const path of Object.keys(spec.paths)) {
+      for (const method of Object.keys(spec.paths[path])) {
+        /* istanbul ignore else */
+        if (isClassDeprecated) {
+          spec.paths[path][method].deprecated = true;
+        }
+        /* istanbul ignore else */
+        if (classTags) {
+          if (
+            spec.paths[path][method].tags &&
+            spec.paths[path][method].tags.length
+          ) {
+            spec.paths[path][method].tags = spec.paths[path][
+              method
+            ].tags.concat(classTags.tags);
+          } else {
+            spec.paths[path][method].tags = classTags.tags;
+          }
+        }
+      }
+    }
+  }
+
   let endpoints =
     MetadataInspector.getAllMethodMetadata<RestEndpoint>(
       OAI3Keys.METHODS_KEY,
@@ -91,6 +133,23 @@ function resolveControllerSpec(constructor: Function): ControllerSpec {
     const verb = endpoint.verb!;
     const path = endpoint.path!;
 
+    const isMethodDeprecated = MetadataInspector.getMethodMetadata<boolean>(
+      OAI3Keys.DEPRECATED_METHOD_KEY,
+      constructor.prototype,
+      op,
+    );
+    if (isMethodDeprecated) {
+      debug('  using method-level deprecation via @deprecated()');
+    }
+
+    const methodTags = MetadataInspector.getMethodMetadata<
+      TagsDecoratorMetadata
+    >(OAI3Keys.TAGS_METHOD_KEY, constructor.prototype, op);
+
+    if (methodTags) {
+      debug('  using method-level tags via @oas.tags()');
+    }
+
     let endpointName = '';
     /* istanbul ignore if */
     if (debug.enabled) {
@@ -113,10 +172,34 @@ function resolveControllerSpec(constructor: Function): ControllerSpec {
       };
       endpoint.spec = operationSpec;
     }
+
+    if (classTags && !operationSpec.tags) {
+      operationSpec.tags = classTags.tags;
+    }
+
+    if (methodTags) {
+      if (operationSpec.tags && operationSpec.tags.length) {
+        operationSpec.tags = operationSpec.tags.concat(methodTags.tags);
+      } else {
+        operationSpec.tags = methodTags.tags;
+      }
+    }
+
     debug('  operation for method %s: %j', op, endpoint);
 
     debug('  spec responses for method %s: %o', op, operationSpec.responses);
 
+    // Prescedence: method decorator > class decorator > operationSpec > undefined
+    const deprecationSpec =
+      isMethodDeprecated ??
+      isClassDeprecated ??
+      operationSpec.deprecated ??
+      false;
+
+    if (deprecationSpec) {
+      operationSpec.deprecated = true;
+    }
+
     for (const code in operationSpec.responses) {
       const responseObject: ResponseObject | ReferenceObject =
         operationSpec.responses[code];
@@ -178,9 +261,11 @@ function resolveControllerSpec(constructor: Function): ControllerSpec {
 
       requestBody = requestBodies[0];
       debug('  requestBody for method %s: %j', op, requestBody);
+      /* istanbul ignore else */
       if (requestBody) {
         operationSpec.requestBody = requestBody;
 
+        /* istanbul ignore else */
         const content = requestBody.content || {};
         for (const mediaType in content) {
           processSchemaExtensions(spec, content[mediaType].schema);
@@ -222,7 +307,7 @@ function resolveControllerSpec(constructor: Function): ControllerSpec {
     const paramTypes = opMetadata.parameterTypes;
 
     const isComplexType = (ctor: Function) =>
-      !_.includes([String, Number, Boolean, Array, Object], ctor);
+      !includes([String, Number, Boolean, Array, Object], ctor);
 
     for (const p of paramTypes) {
       if (isComplexType(p)) {
@@ -233,6 +318,9 @@ function resolveControllerSpec(constructor: Function): ControllerSpec {
   return spec;
 }
 
+declare type MixKey = 'allOf' | 'anyOf' | 'oneOf';
+const SCHEMA_ARR_KEYS: MixKey[] = ['allOf', 'anyOf', 'oneOf'];
+
 /**
  * Resolve the x-ts-type in the schema object
  * @param spec - Controller spec
@@ -248,24 +336,51 @@ function processSchemaExtensions(
   assignRelatedSchemas(spec, schema.definitions);
   delete schema.definitions;
 
-  if (isReferenceObject(schema)) return;
+  /**
+   * check if we have been provided a `not`
+   * `not` is valid in many cases- here we're checking for
+   * `not: { schema: {'x-ts-type': SomeModel }}
+   */
+  if (schema.not) {
+    processSchemaExtensions(spec, schema.not);
+  }
 
-  const tsType = schema[TS_TYPE_KEY];
-  debug('  %s => %o', TS_TYPE_KEY, tsType);
-  if (tsType) {
-    schema = resolveSchema(tsType, schema);
-    if (schema.$ref) generateOpenAPISchema(spec, tsType);
+  /**
+   *  check for schema.allOf, schema.oneOf, schema.anyOf arrays first.
+   *  You cannot provide BOTH a defnintion AND one of these keywords.
+   */
+  /* istanbul ignore else */
+  const hasOwn = (prop: string) => schema?.hasOwnProperty(prop);
+
+  if (SCHEMA_ARR_KEYS.some(k => hasOwn(k))) {
+    SCHEMA_ARR_KEYS.forEach((k: MixKey) => {
+      /* istanbul ignore else */
+      if (schema?.[k] && Array.isArray(schema[k])) {
+        schema[k].forEach((r: (SchemaObject | ReferenceObject)[]) => {
+          processSchemaExtensions(spec, r);
+        });
+      }
+    });
+  } else {
+    if (isReferenceObject(schema)) return;
 
-    // We don't want a Function type in the final spec.
-    delete schema[TS_TYPE_KEY];
-    return;
-  }
-  if (schema.type === 'array') {
-    processSchemaExtensions(spec, schema.items);
-  } else if (schema.type === 'object') {
-    if (schema.properties) {
-      for (const p in schema.properties) {
-        processSchemaExtensions(spec, schema.properties[p]);
+    const tsType = schema[TS_TYPE_KEY];
+    debug('  %s => %o', TS_TYPE_KEY, tsType);
+    if (tsType) {
+      schema = resolveSchema(tsType, schema);
+      if (schema.$ref) generateOpenAPISchema(spec, tsType);
+
+      // We don't want a Function type in the final spec.
+      delete schema[TS_TYPE_KEY];
+      return;
+    }
+    if (schema.type === 'array') {
+      processSchemaExtensions(spec, schema.items);
+    } else if (schema.type === 'object') {
+      if (schema.properties) {
+        for (const p in schema.properties) {
+          processSchemaExtensions(spec, schema.properties[p]);
+        }
       }
     }
   }

package/src/decorators/api.decorator.ts

@@ -3,7 +3,7 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import {ClassDecoratorFactory} from '@loopback/context';
+import {ClassDecoratorFactory} from '@loopback/core';
 import {ControllerSpec} from '../controller-spec';
 import {OAI3Keys} from '../keys';
 

package/src/decorators/deprecated.decorator.ts

@@ -0,0 +1,87 @@
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: @loopback/openapi-v3
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import {
+  ClassDecoratorFactory,
+  DecoratorFactory,
+  MethodDecoratorFactory,
+} from '@loopback/core';
+import {OAI3Keys} from '../keys';
+
+const debug = require('debug')(
+  'loopback:openapi3:metadata:controller-spec:deprecated',
+);
+
+/**
+ * Marks an api path as deprecated.  When applied to a class, this decorator
+ * marks all paths as deprecated.
+ *
+ * You can optionally mark all controllers in a class as deprecated, but use
+ * `@deprecated(false)` on a specific method to ensure it is not marked
+ * as deprecated in the specification.
+ *
+ * @param isDeprecated - whether or not the path should be marked as deprecated.
+ *        This is useful for marking a class as deprecated, but a method as
+ *        not deprecated.
+ *
+ * @example
+ * ```ts
+ * @oas.deprecated()
+ * class MyController {
+ *   @get('/greet')
+ *   public async function greet() {
+ *     return 'Hello, World!'
+ *   }
+ *
+ *   @get('/greet-v2')
+ *   @oas.deprecated(false)
+ *   public async function greetV2() {
+ *     return 'Hello, World!'
+ *   }
+ * }
+ *
+ * class MyOtherController {
+ *   @get('/echo')
+ *   public async function echo() {
+ *     return 'Echo!'
+ *   }
+ * }
+ * ```
+ */
+export function deprecated(isDeprecated = true) {
+  return function deprecatedDecoratorForClassOrMethod(
+    // Class or a prototype
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    target: any,
+    method?: string,
+    // Use `any` to for `TypedPropertyDescriptor`
+    // See https://github.com/strongloop/loopback-next/pull/2704
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    methodDescriptor?: TypedPropertyDescriptor<any>,
+  ) {
+    debug(target, method, methodDescriptor);
+
+    if (method && methodDescriptor) {
+      // Method
+      return MethodDecoratorFactory.createDecorator<boolean>(
+        OAI3Keys.DEPRECATED_METHOD_KEY,
+        isDeprecated,
+        {decoratorName: '@oas.deprecated'},
+      )(target, method, methodDescriptor);
+    } else if (typeof target === 'function' && !method && !methodDescriptor) {
+      // Class
+      return ClassDecoratorFactory.createDecorator<boolean>(
+        OAI3Keys.DEPRECATED_CLASS_KEY,
+        isDeprecated,
+        {decoratorName: '@oas.deprecated'},
+      )(target);
+    } else {
+      throw new Error(
+        '@oas.deprecated cannot be used on a property: ' +
+          DecoratorFactory.getTargetName(target, method, methodDescriptor),
+      );
+    }
+  };
+}

package/src/decorators/index.ts

@@ -4,6 +4,36 @@
 // License text available at https://opensource.org/licenses/MIT
 
 export * from './api.decorator';
+export * from './deprecated.decorator';
 export * from './operation.decorator';
 export * from './parameter.decorator';
 export * from './request-body.decorator';
+
+import {api} from './api.decorator';
+import {deprecated} from './deprecated.decorator';
+import {del, get, operation, patch, post, put} from './operation.decorator';
+import {param} from './parameter.decorator';
+import {requestBody} from './request-body.decorator';
+import {tags} from './tags.decorator';
+
+export const oas = {
+  api,
+  operation,
+
+  // methods
+  get,
+  post,
+  del,
+  patch,
+  put,
+
+  //param
+  param,
+
+  // request body
+  requestBody,
+
+  // oas convenience decorators
+  deprecated,
+  tags,
+};

package/src/decorators/operation.decorator.ts

@@ -3,7 +3,7 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import {MethodDecoratorFactory} from '@loopback/context';
+import {MethodDecoratorFactory} from '@loopback/core';
 import {RestEndpoint} from '../controller-spec';
 import {OAI3Keys} from '../keys';
 import {OperationObject} from '../types';

package/src/decorators/parameter.decorator.ts

@@ -3,7 +3,7 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import {MetadataInspector, ParameterDecoratorFactory} from '@loopback/context';
+import {MetadataInspector, ParameterDecoratorFactory} from '@loopback/core';
 import {resolveSchema} from '../generate-schema';
 import {OAI3Keys} from '../keys';
 import {
@@ -50,8 +50,11 @@ export function param(paramSpec: ParameterObject) {
         // generate schema if `paramSpec` has `schema` but without `type`
         (isSchemaObject(paramSpec.schema) && !paramSpec.schema.type)
       ) {
-        // please note `resolveSchema` only adds `type` and `format` for `schema`
-        paramSpec.schema = resolveSchema(paramType, paramSpec.schema);
+        // If content explicitly mentioned do not resolve schema
+        if (!paramSpec.content) {
+          // please note `resolveSchema` only adds `type` and `format` for `schema`
+          paramSpec.schema = resolveSchema(paramType, paramSpec.schema);
+        }
       }
     }
 
@@ -212,9 +215,11 @@ export namespace param {
       return param({
         name,
         in: 'query',
-        style: 'deepObject',
-        explode: true,
-        schema,
+        content: {
+          'application/json': {
+            schema,
+          },
+        },
         ...spec,
       });
     },

package/src/decorators/request-body.decorator.ts

@@ -3,7 +3,7 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import {MetadataInspector, ParameterDecoratorFactory} from '@loopback/context';
+import {MetadataInspector, ParameterDecoratorFactory} from '@loopback/core';
 import _ from 'lodash';
 import {inspect} from 'util';
 import {resolveSchema} from '../generate-schema';

package/src/decorators/tags.decorator.ts

@@ -0,0 +1,46 @@
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: @loopback/openapi-v3
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import {
+  ClassDecoratorFactory,
+  DecoratorFactory,
+  MethodDecoratorFactory,
+} from '@loopback/core';
+import {OAI3Keys} from '../keys';
+import {TagsDecoratorMetadata} from '../types';
+
+export function tags(...tagNames: string[]) {
+  return function tagsDecoratorForClassOrMethod(
+    // Class or a prototype
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    target: any,
+    method?: string,
+    // Use `any` to for `TypedPropertyDescriptor`
+    // See https://github.com/strongloop/loopback-next/pull/2704
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    methodDescriptor?: TypedPropertyDescriptor<any>,
+  ) {
+    if (method && methodDescriptor) {
+      // Method
+      return MethodDecoratorFactory.createDecorator<TagsDecoratorMetadata>(
+        OAI3Keys.TAGS_METHOD_KEY,
+        {tags: tagNames},
+        {decoratorName: '@oas.tags'},
+      )(target, method, methodDescriptor);
+    } else if (typeof target === 'function' && !method && !methodDescriptor) {
+      // Class
+      return ClassDecoratorFactory.createDecorator<TagsDecoratorMetadata>(
+        OAI3Keys.TAGS_CLASS_KEY,
+        {tags: tagNames},
+        {decoratorName: '@oas.tags'},
+      )(target);
+    } else {
+      throw new Error(
+        '@oas.tags cannot be used on a property: ' +
+          DecoratorFactory.getTargetName(target, method, methodDescriptor),
+      );
+    }
+  };
+}

package/src/enhancers/index.ts

@@ -0,0 +1,8 @@
+// Copyright IBM Corp. 2019. All Rights Reserved.
+// Node module: @loopback/openapi-v3
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+export * from './keys';
+export * from './spec-enhancer.service';
+export * from './types';

package/src/enhancers/keys.ts

@@ -0,0 +1,14 @@
+// Copyright IBM Corp. 2019. All Rights Reserved.
+// Node module: @loopback/openapi-v3
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import {BindingKey} from '@loopback/core';
+import {OASEnhancerService} from './spec-enhancer.service';
+
+/**
+ * Strongly-typed binding key for SpecService
+ */
+export const OAS_ENHANCER_SERVICE = BindingKey.create<OASEnhancerService>(
+  'services.SpecService',
+);

package/src/enhancers/spec-enhancer.service.ts

@@ -0,0 +1,121 @@
+// Copyright IBM Corp. 2019. All Rights Reserved.
+// Node module: @loopback/openapi-v3
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import {config, extensionPoint, extensions, Getter} from '@loopback/core';
+import debugModule from 'debug';
+import * as _ from 'lodash';
+import {inspect} from 'util';
+import {OpenApiSpec} from '../types';
+import {OASEnhancer, OAS_ENHANCER_EXTENSION_POINT_NAME} from './types';
+const jsonmergepatch = require('json-merge-patch');
+
+const debug = debugModule('loopback:openapi:spec-enhancer');
+
+/**
+ * Options for the OpenAPI Spec enhancer extension point
+ */
+export interface OASEnhancerServiceOptions {
+  // no-op
+}
+
+/**
+ * An extension point for OpenAPI Spec enhancement
+ * This service is used for enhancing an OpenAPI spec by loading and applying one or more
+ * registered enhancers.
+ *
+ * A typical use of it would be generating the OpenAPI spec for the endpoints on a server
+ * in the `@loopback/rest` module.
+ */
+@extensionPoint(OAS_ENHANCER_EXTENSION_POINT_NAME)
+export class OASEnhancerService {
+  constructor(
+    /**
+     * Inject a getter function to fetch spec enhancers
+     */
+    @extensions()
+    private getEnhancers: Getter<OASEnhancer[]>,
+    /**
+     * An extension point should be able to receive its options via dependency
+     * injection.
+     */
+    @config()
+    public readonly options?: OASEnhancerServiceOptions,
+  ) {}
+
+  private _spec: OpenApiSpec = {
+    openapi: '3.0.0',
+    info: {
+      title: 'LoopBack Application',
+      version: '1.0.0',
+    },
+    paths: {},
+  };
+
+  /**
+   * Getter for `_spec`
+   */
+  get spec(): OpenApiSpec {
+    return this._spec;
+  }
+  /**
+   * Setter for `_spec`
+   */
+  set spec(value: OpenApiSpec) {
+    this._spec = value;
+  }
+
+  /**
+   * Find an enhancer by its name
+   * @param name The name of the enhancer you want to find
+   */
+  async getEnhancerByName(name: string): Promise<OASEnhancer | undefined> {
+    // Get the latest list of enhancers
+    const enhancers = await this.getEnhancers();
+    return enhancers.find(e => e.name === name);
+  }
+
+  /**
+   * Apply a given enhancer's merge function. Return the latest _spec.
+   * @param name The name of the enhancer you want to apply
+   */
+  async applyEnhancerByName(name: string): Promise<OpenApiSpec> {
+    const enhancer = await this.getEnhancerByName(name);
+    if (enhancer) this._spec = enhancer.modifySpec(this._spec);
+    return this._spec;
+  }
+
+  /**
+   * Generate OpenAPI spec by applying ALL registered enhancers
+   * TBD: load enhancers by group names
+   */
+  async applyAllEnhancers(options = {}): Promise<OpenApiSpec> {
+    const enhancers = await this.getEnhancers();
+    if (_.isEmpty(enhancers)) return this._spec;
+    for (const e of enhancers) {
+      this._spec = e.modifySpec(this._spec);
+    }
+    debug(`Spec enhancer service, generated spec: ${inspect(this._spec)}`);
+    return this._spec;
+  }
+}
+
+/**
+ * The default merge function to patch the current OpenAPI spec.
+ * It leverages module `json-merge-patch`'s merge API to merge two json objects.
+ * It returns a new merged object without modifying the original one.
+ *
+ * A list of merging rules can be found in test file:
+ * https://github.com/pierreinglebert/json-merge-patch/blob/master/test/lib/merge.js
+ *
+ * @param currentSpec The original spec
+ * @param patchSpec The patch spec to be merged into the original spec
+ */
+export function mergeOpenAPISpec(
+  currentSpec: Partial<OpenApiSpec>,
+  patchSpec: Partial<OpenApiSpec>,
+) {
+  const mergedSpec = jsonmergepatch.merge(currentSpec, patchSpec);
+  return mergedSpec;
+}