@loopback/openapi-v3 1.10.2 → 1.13.0

package/package.json

@@ -1,26 +1,27 @@
 {
   "name": "@loopback/openapi-v3",
-  "version": "1.10.2",
+  "version": "1.13.0",
   "description": "Processes openapi v3 related metadata",
   "engines": {
     "node": ">=8.9"
   },
   "dependencies": {
-    "@loopback/context": "^1.24.0",
-    "@loopback/repository-json-schema": "^1.11.2",
+    "@loopback/core": "^1.12.3",
+    "@loopback/repository-json-schema": "^1.12.1",
     "debug": "^4.1.1",
+    "json-merge-patch": "^0.2.3",
     "lodash": "^4.17.15",
     "openapi3-ts": "^1.3.0"
   },
   "devDependencies": {
-    "@loopback/build": "^2.1.0",
-    "@loopback/eslint-config": "^4.1.5",
-    "@loopback/openapi-spec-builder": "^1.2.19",
-    "@loopback/repository": "^1.15.5",
-    "@loopback/testlab": "^1.9.5",
+    "@loopback/build": "^3.1.1",
+    "@loopback/eslint-config": "^5.0.3",
+    "@loopback/openapi-spec-builder": "^1.3.1",
+    "@loopback/repository": "^1.19.0",
+    "@loopback/testlab": "^1.10.3",
     "@types/debug": "^4.1.5",
     "@types/lodash": "^4.14.149",
-    "@types/node": "^10.17.5"
+    "@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": "c111543a6139c5a2999930c593aabbbdf10a838e"
+  "gitHead": "b5e53892d327c6cf4c6023055d2b38f13fe4729e"
 }

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 * as _ 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,11 +78,52 @@ 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,
       constructor.prototype,
-    ) || {};
+    ) ?? {};
 
   endpoints = DecoratorFactory.cloneDeep(endpoints);
   for (const op in endpoints) {
@@ -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,15 +172,39 @@ 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];
       if (isReferenceObject(responseObject)) continue;
-      const content = responseObject.content || {};
+      const content = responseObject.content ?? {};
       for (const c in content) {
         debug('  processing response code %s with content-type %', code, c);
         processSchemaExtensions(spec, content[c].schema);
@@ -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 {
@@ -37,7 +37,7 @@ export function param(paramSpec: ParameterObject) {
     paramSpec = paramSpec || {};
     // Get the design time method parameter metadata
     const methodSig = MetadataInspector.getDesignTypeForMethod(target, member);
-    const paramTypes = (methodSig && methodSig.parameterTypes) || [];
+    const paramTypes = methodSig?.parameterTypes || [];
 
     // Map design-time parameter type to the OpenAPI param type
 

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

@@ -3,8 +3,8 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import {MetadataInspector, ParameterDecoratorFactory} from '@loopback/context';
-import * as _ from 'lodash';
+import {MetadataInspector, ParameterDecoratorFactory} from '@loopback/core';
+import _ from 'lodash';
 import {inspect} from 'util';
 import {resolveSchema} from '../generate-schema';
 import {OAI3Keys} from '../keys';
@@ -86,14 +86,14 @@ export function requestBody(requestBodySpec?: Partial<RequestBodyObject>) {
       debug('  options: %s', inspect(requestBodySpec, {depth: null}));
 
     // Use 'application/json' as default content if `requestBody` is undefined
-    requestBodySpec = requestBodySpec || {content: {}};
+    requestBodySpec = requestBodySpec ?? {content: {}};
 
     if (_.isEmpty(requestBodySpec.content))
       requestBodySpec.content = {'application/json': {}};
 
     // Get the design time method parameter metadata
     const methodSig = MetadataInspector.getDesignTypeForMethod(target, member);
-    const paramTypes = (methodSig && methodSig.parameterTypes) || [];
+    const paramTypes = methodSig?.parameterTypes || [];
 
     const paramType = paramTypes[index];
     const schema = resolveSchema(paramType);

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;
+}