Custom schema title for POST requests

docs/site/Controller-generator.md

@@ -134,7 +134,7 @@ export class TodoController {
     @requestBody({
       content: {
         'application/json': {
-          schema: getModelSchemaRef(Todo, {exclude: ['id']}),
+          schema: getModelSchemaRef(Todo, {title: 'NewTodo', exclude: ['id']}),
         },
       },
     })

docs/site/tutorials/todo-list/todo-list-tutorial-controller.md

@@ -181,7 +181,7 @@ export class TodoListTodoController {
     @requestBody({
       content: {
         'application/json': {
-          schema: getModelSchemaRef(Todo, {exclude: ['id']}),
+          schema: getModelSchemaRef(Todo, {title: 'NewTodo', exclude: ['id']}),
         },
       },
     })
@@ -237,7 +237,7 @@ export class TodoListTodoController {
     @requestBody({
       content: {
         'application/json': {
-          schema: getModelSchemaRef(Todo, {exclude: ['id']}),
+          schema: getModelSchemaRef(Todo, {title: 'NewTodo', exclude: ['id']}),
         },
       },
     })

examples/express-composition/src/controllers/note.controller.ts

@@ -43,7 +43,7 @@ export class NoteController {
     @requestBody({
       content: {
         'application/json': {
-          schema: getModelSchemaRef(Note, {exclude: ['id']}),
+          schema: getModelSchemaRef(Note, {title: 'NewNote', exclude: ['id']}),
         },
       },
     })

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

@@ -42,6 +42,7 @@ export class TodoListTodoController {
       content: {
         'application/json': {
           schema: getModelSchemaRef(Todo, {
+            title: 'NewTodoInTodoList',
             exclude: ['id'],
             optional: ['todoListId'],
           }),

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

@@ -42,7 +42,10 @@ export class TodoListController {
     @requestBody({
       content: {
         'application/json': {
-          schema: getModelSchemaRef(TodoList, {exclude: ['id']}),
+          schema: getModelSchemaRef(TodoList, {
+            title: 'NewTodoList',
+            exclude: ['id'],
+          }),
         },
       },
     })

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

@@ -33,7 +33,7 @@ export class TodoController {
     @requestBody({
       content: {
         'application/json': {
-          schema: getModelSchemaRef(Todo, {exclude: ['id']}),
+          schema: getModelSchemaRef(Todo, {title: 'NewTodo', exclude: ['id']}),
         },
       },
     })

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

@@ -38,7 +38,7 @@ export class TodoController {
     @requestBody({
       content: {
         'application/json': {
-          schema: getModelSchemaRef(Todo, {exclude: ['id']}),
+          schema: getModelSchemaRef(Todo, {title: 'NewTodo', exclude: ['id']}),
         },
       },
     })

packages/cli/generators/controller/templates/src/controllers/controller-rest-template.ts.ejs

@@ -38,7 +38,10 @@ export class <%= className %>Controller {
     @requestBody({
       content: {
         'application/json': {
-          schema: getModelSchemaRef(<%= modelName %>, {exclude: ['<%= id %>']}),
+          schema: getModelSchemaRef(<%= modelName %>, {
+            title: 'New<%= modelName %>',
+            exclude: ['<%= id %>'],
+          }),
         },
       },
     })

packages/cli/generators/relation/templates/controller-relation-template-has-many.ts.ejs

@@ -59,6 +59,7 @@ export class <%= controllerClassName %> {
       content: {
         'application/json': {
           schema: getModelSchemaRef(<%= targetModelClassName %>, {
+            title: 'New <%= targetModelClassName %>In<%= sourceModelClassName %>',
             exclude: ['<%= targetModelPrimaryKey %>'],
             optional: ['<%= foreignKeyName %>']
           }),

packages/cli/test/integration/generators/controller.integration.js

@@ -249,7 +249,7 @@ function checkRestCrudContents() {
     /'200': {/,
     /description: 'ProductReview model instance'/,
     /content: {'application\/json': {schema: getModelSchemaRef\(ProductReview\)}},\s{1,}},\s{1,}},\s{1,}}\)/,
-    /async create\(\s+\@requestBody\({\s+content: {\s+'application\/json': {\s+schema: getModelSchemaRef\(ProductReview, {exclude: \['productId'\]}\),\s+},\s+},\s+}\)\s+productReview: Omit<ProductReview, 'productId'>,\s+\)/,
+    /async create\(\s+\@requestBody\({\s+content: {\s+'application\/json': {\s+schema: getModelSchemaRef\(ProductReview, {\s+title: 'NewProductReview',\s+exclude: \['productId'\],\s+}\),\s+},\s+},\s+}\)\s+productReview: Omit<ProductReview, 'productId'>,\s+\)/,
   ];
   postCreateRegEx.forEach(regex => {
     assert.fileContent(expectedFile, regex);

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

@@ -630,6 +630,34 @@ describe('build-schema', () => {
         expect(schema).to.deepEqual(expectedSchema);
       });
     });
+
+    it('uses title from model metadata instead of model name', () => {
+      @model({title: 'MyCustomer'})
+      class Customer {}
+
+      const schema = modelToJsonSchema(Customer, {
+        // trigger build of a custom title
+        partial: true,
+      });
+
+      expect(schema.title).to.equal('MyCustomerPartial');
+    });
+
+    it('uses title from options instead of model name and computed suffix', () => {
+      @model({title: 'ShouldBeIgnored'})
+      class TestModel {
+        @property()
+        id: string;
+      }
+
+      const schema = modelToJsonSchema(TestModel, {
+        title: 'NewTestModel',
+        partial: true,
+        exclude: ['id'],
+      });
+
+      expect(schema.title).to.equal('NewTestModel');
+    });
   });
 
   describe('getJsonSchema', () => {
@@ -1082,5 +1110,21 @@ describe('build-schema', () => {
         expect(optionalNameSchema.title).to.equal('ProductPartial');
       });
     });
+
+    it('creates new cache entry for each custom title', () => {
+      @model()
+      class TestModel {}
+
+      // populate the cache
+      getJsonSchema(TestModel, {title: 'First'});
+      getJsonSchema(TestModel, {title: 'Second'});
+
+      // obtain cached instances & verify the title
+      const schema1 = getJsonSchema(TestModel, {title: 'First'});
+      expect(schema1.title).to.equal('First');
+
+      const schema2 = getJsonSchema(TestModel, {title: 'Second'});
+      expect(schema2.title).to.equal('Second');
+    });
   });
 });

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

@@ -325,5 +325,10 @@ describe('build-schema', () => {
         'modelOptional[name]Excluding[id,_rev]WithRelations',
       );
     });
+
+    it('includes custom title', () => {
+      const key = buildModelCacheKey({title: 'NewProduct', partial: true});
+      expect(key).to.equal('modelNewProductPartial');
+    });
   });
 });

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

@@ -18,6 +18,15 @@ import {JSON_SCHEMA_KEY, MODEL_TYPE_KEYS} from './keys';
 const debug = debugFactory('loopback:repository-json-schema:build-schema');
 
 export interface JsonSchemaOptions<T extends object> {
+  /**
+   * The title to use in the generated schema.
+   *
+   * When using options like `exclude`, the auto-generated title can be
+   * difficult to read for humans. Use this option to change the title to
+   * a more meaningful value.
+   */
+  title?: string;
+
   /**
    * Set this flag if you want the schema to define navigational properties
    * for model relations.
@@ -62,7 +71,7 @@ export function buildModelCacheKey<T extends object>(
   // New key schema: use the same suffix as we use for schema title
   // For example: "modelPartialWithRelations"
   // Note this new key schema preserves the old key "modelWithRelations"
-  return 'model' + getTitleSuffix(options);
+  return 'model' + (options.title || '') + getTitleSuffix(options);
 }
 
 /**
@@ -271,6 +280,16 @@ export function getNavigationalPropertyForRelation(
   }
 }
 
+function buildSchemaTitle<T extends object>(
+  ctor: Function & {prototype: T},
+  meta: ModelDefinition,
+  options: JsonSchemaOptions<T>,
+) {
+  if (options.title) return options.title;
+  const title = meta.title || ctor.name;
+  return title + getTitleSuffix(options);
+}
+
 function getTitleSuffix<T extends object>(options: JsonSchemaOptions<T> = {}) {
   let suffix = '';
   if (options.optional && options.optional.length) {
@@ -319,7 +338,7 @@ export function modelToJsonSchema<T extends object>(
     return {};
   }
 
-  const title = (meta.title || ctor.name) + getTitleSuffix(options);
+  const title = buildSchemaTitle(ctor, meta, options);
 
   if (options.visited[title]) return options.visited[title];
 

packages/rest-crud/src/crud-rest.controller.ts

@@ -152,7 +152,10 @@ export function defineCrudRestController<
       ...response.model(200, `${modelName} instance created`, modelCtor),
     })
     async create(
-      @body(modelCtor, {exclude: modelCtor.getIdProperties() as (keyof T)[]})
+      @body(modelCtor, {
+        title: `New${modelName}`,
+        exclude: modelCtor.getIdProperties() as (keyof T)[],
+      })
       data: Omit<T, IdName>,
     ): Promise<T> {
       return this.repository.create(