Emit schema excluding certain model properties

[bajtos]

Allow Controller methods implementing CREATE operation to describe their input data as "a model without id and _rev properties ". This story requires #2629 and #2631 to be implemented first.

To emit schema with certain properties excluded, we should add a new schema-generation option called exclude & accepting a list of property names to remove from the schema. To allow TypeScript compiler to verify that exclude items are valid property names, we should leverage TypeScript generics and keyof keyword.

export interface JsonSchemaOptions<T extends object = any>{
  /// List of properties to exclude from the schema
  exclude?: (keyof T)[];
}

An example showing a controller method excluding the property id:

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: Omit<TodoList, 'id'>,
    /***** ^^^ THIS IS IMPORTANT - TYPESCRIPT TYPE ^^^ ****/
  ): Promise<TodoList> {
    return await this.todoListRepository.create(obj);
  }
}

See 887ae84 for a spike showing proposed implementation details.

Acceptance criteria

• A type alias for Pick<T, Exclude<keyof TodoList, K>>, see the discussion in 887ae84#r269305305 - not needed, TypeScript has recently introduced Omit type.

• Implementation including test coverage

• API documentation

• CREATE endpoints in all example applications are updated to leverage exclude option to remove id property and use the new type alias as the type of the controller method argument accepting model data.

• CLI templates are updated accordingly

• Should have - create a new issue if it's too difficult to implement:

  Controller methods working with related models should exclude the foreign key from request body properties. Cross-posting from Epic: Validation at Model/ORM level #1872 (comment):

  myRepo.users(tenantId).create(new User(...)) fails unless "tenantId" is explicitly passed in the request body even though the relation automatically attaches the "tenantId" property.

  Things to change: example-todo-list, CLI template for relational controllers (has-many, belongs-to)

• Review the following issues , either close them as fixed or post a comment explaining what's remaining to be done:

  • OpenAPI decorator does not properly generate schemas of type Partial #1179
  • [API Explorer] Fields shown but ignored #1470
  • relation expects foreignKey on the Object #1719
  • fix(rest): allow @patch update obj to be a Partial #1894

[bajtos]

Pick<TodoList, Exclude<keyof TodoList, 'id'>>

TypeScript 3.5 is going to introduce a new type Omit (see the announcement post), let's leverage it here.

- Pick<TodoList, Exclude<keyof TodoList, 'id'>>`
+ Omit<TodoList, 'id'>

[bajtos]

@nabdelgadir What is the remaining work now that #3309 was landed? Could you please update checkboxes in the acceptance criteria to match the new status and perhaps add a new task for adding support for PK with a custom name (not id).

[nabdelgadir]

@bajtos I'm assuming you were referring to #3297, but after #3309 is landed we can close this issue.

perhaps add a new task for adding support for PK with a custom name (not id).

I'm working on custom names but I'll create the new issue so we can close this one after #3309 is landed.

New issue: #3344.