feat: add include and partial flags to JsonSchemaOptions

Author: bajtos

_SPIKE_.md

@@ -7,3 +7,172 @@ issue for the discussions we already have had in the past.
 The code in this spike is building on top of the spike for Inclusion of related
 models ([PR#2592)(https://github.com/strongloop/loopback-next/pull/2592)),
 please ignore the first commit.
+
+## Overview
+
+I am proposing to leverage the interface `JsonSchemaOptions` and
+`getModelSchemaRef` helper to build schema with additional constraints. Later
+on, we can explore different ways how to enable includeRelations flag via
+OpenAPI spec extensions.
+
+### Exclude properties from CREATE requests
+
+An example showing a controller method excluding the property `id`:
+
+```ts
+class TodoListController {
+  // ...
+
+  @post('/todo-lists', {
+    responses: {
+      // left out for brevity
+    },
+  })
+  async create(
+    @requestBody({
+      content: {
+        'application/json': {
+          schema: getModelSchemaRef(TodoList, {exclude: ['id']}),
+          /***** ^^^ THIS IS IMPORTANT - OPENAPI SCHEMA ^^^ ****/
+        },
+      },
+    })
+    obj: Pick<TodoList, Exclude<keyof TodoList, 'id'>>,
+    /***** ^^^ THIS IS IMPORTANT - TYPESCRIPT TYPE ^^^ ****/
+  ): Promise<TodoList> {
+    return await this.todoListRepository.create(obj);
+  }
+}
+```
+
+An example schema produced by the helper in the request body spec:
+
+```json
+{
+  "requestBody": {
+    "content": {
+      "application/json": {
+        "schema": {
+          "$ref": "#/components/schemas/TodoListWithout(id)"
+        }
+      }
+    }
+  }
+}
+```
+
+The full schema in component schemas:
+
+```json
+{
+  "TodoListWithout(id)": {
+    "title": "TodoListWithout(id)",
+    "properties": {
+      "title": {
+        "type": "string"
+      },
+      "color": {
+        "type": "string"
+      }
+    },
+    "required": ["title"]
+  }
+}
+```
+
+### Mark all properties as optional
+
+An example showing a controller method accepting a partial model instance:
+
+```ts
+class TodoListController {
+  // ...
+
+  @patch('/todo-lists/{id}', {
+    responses: {
+      // left out for brevity
+    },
+  })
+  async updateById(
+    @param.path.number('id') id: number,
+    @requestBody({
+      content: {
+        'application/json': {
+          schema: getModelSchemaRef(TodoList, {partial: true}),
+          /***** ^^^ THIS IS IMPORTANT - OPENAPI SCHEMA ^^^ ****/
+        },
+      },
+    })
+    obj: Partial<TodoList>,
+    /***** ^^^ THIS IS IMPORTANT - TYPESCRIPT TYPE ^^^ ****/
+  ): Promise<void> {
+    await this.todoListRepository.updateById(id, obj);
+  }
+}
+```
+
+An example schema in components:
+
+```json
+{
+  "TodoListPartial": {
+    "title": "TodoListPartial",
+    "properties": {
+      "id": {
+        "type": "number"
+      },
+      "title": {
+        "type": "string"
+      },
+      "color": {
+        "type": "string"
+      }
+    }
+  }
+}
+```
+
+### Using spec extension instead of a code-first helper
+
+Later on, we can explore different ways how to enable `partial` and `exclude`
+flags via OpenAPI spec extensions. For example:
+
+```
+schema: {'x-ts-type': Category, 'x-partial': true},
+schema: {'x-ts-type': Category, 'x-exclude': ['id']},
+```
+
+In
+https://github.com/strongloop/loopback-next/issues/1722#issuecomment-422439405,
+a different format was proposed:
+
+```
+schema: {
+  'x-ts-type': Order,
+  'x-ts-type-options': {
+    partial: true,
+    exclude: []
+  }
+}
+```
+
+Either way, I am proposing to leave this part out of the initial implementation.
+
+## Follow-up stories
+
+1. Wait until the following stories from "Inclusion of related models" are
+   implemented:
+
+   1. Support `schema: {$ref, definitions}` in resolveControllerSpec
+      [#2629](https://github.com/strongloop/loopback-next/issues/2629)
+
+   2. Implement `getJsonSchemaRef` and `getModelSchemaRef` helpers
+      [#2631](https://github.com/strongloop/loopback-next/issues/2631)
+
+2. Enhance `getJsonSchema` with a new flag: `partial?: boolean`, also update CLI
+   templates and example apps accordingly.
+
+3. Enhance `getJsonSchema` with a new flag: `exclude?: string[]`, also update
+   CLI templates and example apps accordingly.
+
+4. Spike: configure `JsonSchemaOptions` via an OpenAPI spec extension

examples/todo-list/src/controllers/todo-list.controller.ts

@@ -14,8 +14,8 @@ import {
   del,
   get,
   getFilterSchemaFor,
-  getWhereSchemaFor,
   getModelSchemaRef,
+  getWhereSchemaFor,
   param,
   patch,
   post,
@@ -38,7 +38,16 @@ export class TodoListController {
       },
     },
   })
-  async create(@requestBody() obj: TodoList): Promise<TodoList> {
+  async create(
+    @requestBody({
+      content: {
+        'application/json': {
+          schema: getModelSchemaRef(TodoList, {exclude: ['id']}),
+        },
+      },
+    })
+    obj: Pick<TodoList, Exclude<keyof TodoList, 'id'>>,
+  ): Promise<TodoList> {
     return await this.todoListRepository.create(obj);
   }
 
@@ -86,7 +95,14 @@ export class TodoListController {
     },
   })
   async updateAll(
-    @requestBody() obj: Partial<TodoList>,
+    @requestBody({
+      content: {
+        'application/json': {
+          schema: getModelSchemaRef(TodoList, {partial: true}),
+        },
+      },
+    })
+    obj: Partial<TodoList>,
     @param.query.object('where', getWhereSchemaFor(TodoList)) where?: Where,
   ): Promise<Count> {
     return await this.todoListRepository.updateAll(obj, where);
@@ -113,7 +129,14 @@ export class TodoListController {
   })
   async updateById(
     @param.path.number('id') id: number,
-    @requestBody() obj: TodoList,
+    @requestBody({
+      content: {
+        'application/json': {
+          schema: getModelSchemaRef(TodoList, {partial: true}),
+        },
+      },
+    })
+    obj: Partial<TodoList>,
   ): Promise<void> {
     await this.todoListRepository.updateById(id, obj);
   }

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

@@ -3,29 +3,28 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import {MetadataInspector, DecoratorFactory} from '@loopback/context';
-
+import {DecoratorFactory, MetadataInspector} from '@loopback/context';
 import {
+  ComponentsObject,
+  ISpecificationExtension,
+  isReferenceObject,
   OperationObject,
   ParameterObject,
   PathObject,
-  ComponentsObject,
+  ReferenceObject,
   RequestBodyObject,
   ResponseObject,
-  ReferenceObject,
   SchemaObject,
-  isReferenceObject,
-  ISpecificationExtension,
 } from '@loopback/openapi-v3-types';
 import {
   getJsonSchema,
-  JsonSchemaOptions,
   getJsonSchemaRef,
+  JsonSchemaOptions,
 } from '@loopback/repository-json-schema';
-import {OAI3Keys} from './keys';
-import {jsonToSchemaObject} from './json-to-schema';
 import * as _ from 'lodash';
 import {resolveSchema} from './generate-schema';
+import {jsonToSchemaObject} from './json-to-schema';
+import {OAI3Keys} from './keys';
 
 const debug = require('debug')('loopback:openapi3:metadata:controller-spec');
 
@@ -349,9 +348,9 @@ export function getControllerSpec(constructor: Function): ControllerSpec {
   return spec;
 }
 
-export function getModelSchemaRef(
-  modelCtor: Function,
-  options: JsonSchemaOptions,
+export function getModelSchemaRef<T extends object = any>(
+  modelCtor: Function & {prototype: T},
+  options: JsonSchemaOptions<T> = {},
 ) {
   const jsonSchema = getJsonSchemaRef(modelCtor, options);
   return jsonToSchemaObject(jsonSchema);

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

@@ -582,7 +582,7 @@ describe('build-schema', () => {
       };
       MetadataInspector.defineMetadata(
         JSON_SCHEMA_KEY,
-        {modelOnly: cachedSchema},
+        {'config:{}': cachedSchema},
         TestModel,
       );
       const jsonSchema = getJsonSchema(TestModel);