feat: helpers for building JSON/OpenAPI schema referencing shared definitions

Introduce the following helpers:

- `getModelSchemaRef` returning OpenAPI spec
- `getJsonSchemaRef` returning JSON Schema

Signed-off-by: Miroslav Bajtoš <mbajtoss@gmail.com>

Author: bajtos

packages/openapi-v3/src/__tests__/integration/controller-spec.integration.ts

@@ -18,6 +18,7 @@ import {
   param,
   post,
   requestBody,
+  getModelSchemaRef,
 } from '../..';
 
 describe('controller spec', () => {
@@ -733,4 +734,51 @@ describe('controller spec', () => {
       return MyController;
     }
   });
+
+  describe('getModelSchemaRef', () => {
+    it('creates spec referencing shared model schema', () => {
+      @model()
+      class MyModel {
+        @property()
+        name: string;
+      }
+
+      class MyController {
+        @get('/my', {
+          responses: {
+            '200': {
+              description: 'Array of MyModel model instances',
+              content: {
+                'application/json': {
+                  schema: getModelSchemaRef(MyModel),
+                },
+              },
+            },
+          },
+        })
+        async find(): Promise<MyModel[]> {
+          return [];
+        }
+      }
+
+      const spec = getControllerSpec(MyController);
+      const opSpec: OperationObject = spec.paths['/my'].get;
+      const responseSpec = opSpec.responses['200'].content['application/json'];
+      expect(responseSpec.schema).to.deepEqual({
+        $ref: '#/components/schemas/MyModel',
+      });
+
+      const globalSchemas = (spec.components || {}).schemas;
+      expect(globalSchemas).to.deepEqual({
+        MyModel: {
+          title: 'MyModel',
+          properties: {
+            name: {
+              type: 'string',
+            },
+          },
+        },
+      });
+    });
+  });
 });

packages/openapi-v3/src/controller-spec.ts

@@ -15,11 +15,16 @@ import {
   RequestBodyObject,
   ResponseObject,
   SchemaObject,
+  SchemasObject,
 } from '@loopback/openapi-v3-types';
-import {getJsonSchema} from '@loopback/repository-json-schema';
+import {
+  getJsonSchema,
+  getJsonSchemaRef,
+  JsonSchemaOptions,
+} from '@loopback/repository-json-schema';
 import * as _ from 'lodash';
 import {resolveSchema} from './generate-schema';
-import {jsonToSchemaObject} from './json-to-schema';
+import {jsonToSchemaObject, SchemaRef} from './json-to-schema';
 import {OAI3Keys} from './keys';
 
 const debug = require('debug')('loopback:openapi3:metadata:controller-spec');
@@ -56,8 +61,6 @@ export interface RestEndpoint {
 
 export const TS_TYPE_KEY = 'x-ts-type';
 
-type ComponentSchemaMap = {[key: string]: SchemaObject};
-
 /**
  * Build the api spec from class and method level decorations
  * @param constructor - Controller class
@@ -139,7 +142,7 @@ function resolveControllerSpec(constructor: Function): ControllerSpec {
       params = DecoratorFactory.cloneDeep<ParameterObject[]>(params);
       /**
        * If a controller method uses dependency injection, the parameters
-       * might be sparsed. For example,
+       * might be sparse. For example,
        * ```ts
        * class MyController {
        *   greet(
@@ -304,7 +307,7 @@ function generateOpenAPISchema(spec: ControllerSpec, tsType: Function) {
  */
 function assignRelatedSchemas(
   spec: ControllerSpec,
-  definitions?: ComponentSchemaMap,
+  definitions?: SchemasObject,
 ) {
   if (!definitions) return;
   debug(
@@ -348,3 +351,34 @@ export function getControllerSpec(constructor: Function): ControllerSpec {
   }
   return spec;
 }
+
+/**
+ * Describe the provided Model as a reference to a definition shared by multiple
+ * endpoints. The definition is included in the returned schema.
+ *
+ * @example
+ *
+ * ```ts
+ * const schema = {
+ *   $ref: '#/components/schemas/Product',
+ *   definitions: {
+ *     Product: {
+ *       title: 'Product',
+ *       properties: {
+ *         // etc.
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @param modelCtor - The model constructor (e.g. `Product`)
+ * @param options - Additional options
+ */
+export function getModelSchemaRef(
+  modelCtor: Function,
+  options?: JsonSchemaOptions,
+): SchemaRef {
+  const jsonSchema = getJsonSchemaRef(modelCtor, options);
+  return jsonToSchemaObject(jsonSchema) as SchemaRef;
+}

packages/openapi-v3/src/json-to-schema.ts

@@ -3,15 +3,41 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
+import {
+  ReferenceObject,
+  SchemaObject,
+  SchemasObject,
+} from '@loopback/openapi-v3-types';
 import {JsonSchema} from '@loopback/repository-json-schema';
-import {SchemaObject} from '@loopback/openapi-v3-types';
 import * as _ from 'lodash';
 
+/**
+ * Custom LoopBack extension: a reference to Schema object that's bundled
+ * inside `definitions` property.
+ *
+ * @example
+ *
+ * ```ts
+ * const spec: SchemaRef = {
+ *   $ref: '/components/schemas/Product',
+ *   definitions: {
+ *     Product: {
+ *       title: 'Product',
+ *       properties: {
+ *         // etc.
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export type SchemaRef = ReferenceObject & {definitions: SchemasObject};
+
 /**
  * Converts JSON Schemas into a SchemaObject
  * @param json - JSON Schema to convert from
  */
-export function jsonToSchemaObject(json: JsonSchema): SchemaObject {
+export function jsonToSchemaObject(json: JsonSchema): SchemaObject | SchemaRef {
   const result: SchemaObject = {};
   const propsToIgnore = [
     'anyOf',

packages/repository-json-schema/src/__tests__/helpers/expect-valid-json-schema.ts

@@ -0,0 +1,20 @@
+// Copyright IBM Corp. 2019. All Rights Reserved.
+// Node module: @loopback/repository-json-schema
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import {expect} from '@loopback/testlab';
+import * as Ajv from 'ajv';
+import {JsonSchema} from '../..';
+
+export function expectValidJsonSchema(schema: JsonSchema) {
+  const ajv = new Ajv();
+  const validate = ajv.compile(
+    require('ajv/lib/refs/json-schema-draft-06.json'),
+  );
+  const isValid = validate(schema);
+  const result = isValid
+    ? 'JSON Schema is valid'
+    : ajv.errorsText(validate.errors!);
+  expect(result).to.equal('JSON Schema is valid');
+}

packages/repository-json-schema/src/__tests__/integration/build-schema.integration.ts

@@ -12,13 +12,13 @@ import {
   property,
 } from '@loopback/repository';
 import {expect} from '@loopback/testlab';
-import * as Ajv from 'ajv';
 import {
   getJsonSchema,
   JsonSchema,
   JSON_SCHEMA_KEY,
   modelToJsonSchema,
 } from '../..';
+import {expectValidJsonSchema} from '../helpers/expect-valid-json-schema';
 
 describe('build-schema', () => {
   describe('modelToJsonSchema', () => {
@@ -629,21 +629,9 @@ describe('build-schema', () => {
         expect(schema).to.deepEqual(expectedSchema);
       });
     });
-
-    function expectValidJsonSchema(schema: JsonSchema) {
-      const ajv = new Ajv();
-      const validate = ajv.compile(
-        require('ajv/lib/refs/json-schema-draft-06.json'),
-      );
-      const isValid = validate(schema);
-      const result = isValid
-        ? 'JSON Schema is valid'
-        : ajv.errorsText(validate.errors!);
-      expect(result).to.equal('JSON Schema is valid');
-    }
   });
 
-  describe('getjsonSchema', () => {
+  describe('getJsonSchema', () => {
     it('gets cached JSON schema if one exists', () => {
       @model()
       class TestModel {

packages/repository-json-schema/src/__tests__/integration/schema-ref.integration.ts

@@ -0,0 +1,34 @@
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: @loopback/repository-json-schema
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import {model, property} from '@loopback/repository';
+import {expect} from '@loopback/testlab';
+import {getJsonSchemaRef} from '../..';
+
+describe('getJsonSchemaRef', () => {
+  it('creates spec referencing shared model schema', () => {
+    @model()
+    class MyModel {
+      @property()
+      name: string;
+    }
+
+    const spec = getJsonSchemaRef(MyModel);
+
+    expect(spec).to.deepEqual({
+      $ref: '#/definitions/MyModel',
+      definitions: {
+        MyModel: {
+          title: 'MyModel',
+          properties: {
+            name: {
+              type: 'string',
+            },
+          },
+        },
+      },
+    });
+  });
+});

packages/repository-json-schema/src/build-schema.ts

@@ -40,6 +40,50 @@ export function getJsonSchema(
   }
 }
 
+/**
+ * Describe the provided Model as a reference to a definition shared by multiple
+ * endpoints. The definition is included in the returned schema.
+ *
+ * @example
+ *
+ * ```ts
+ * const schema = {
+ *   $ref: '/definitions/Product',
+ *   definitions: {
+ *     Product: {
+ *       title: 'Product',
+ *       properties: {
+ *         // etc.
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @param modelCtor - The model constructor (e.g. `Product`)
+ * @param options - Additional options
+ */
+export function getJsonSchemaRef(
+  modelCtor: Function,
+  options?: JsonSchemaOptions,
+): JSONSchema {
+  const schemaWithDefinitions = getJsonSchema(modelCtor, options);
+  const key = schemaWithDefinitions.title;
+
+  // ctor is not a model
+  if (!key) return schemaWithDefinitions;
+
+  const definitions = Object.assign({}, schemaWithDefinitions.definitions);
+  const schema = Object.assign({}, schemaWithDefinitions);
+  delete schema.definitions;
+  definitions[key] = schema;
+
+  return {
+    $ref: `#/definitions/${key}`,
+    definitions,
+  };
+}
+
 /**
  * Gets the wrapper function of primitives string, number, and boolean
  * @param type - Name of type

packages/rest/src/__tests__/acceptance/validation/validation.acceptance.ts

@@ -17,6 +17,7 @@ import {
   post,
   requestBody,
   RestApplication,
+  SchemaObject,
 } from '../../..';
 import {aBodySpec} from '../../helpers';
 
@@ -45,7 +46,7 @@ describe('Validation at REST level', () => {
   // Add a schema that requires `description`
   const PRODUCT_SPEC_WITH_DESCRIPTION = jsonToSchemaObject(
     getJsonSchema(Product),
-  );
+  ) as SchemaObject;
   PRODUCT_SPEC_WITH_DESCRIPTION.required!.push('description');
 
   // This is the standard use case that most LB4 applications should use.