Spike: simplify requestBody annotation with schema options #2654

This is a follow-up for the discussion started in #2082, #2152 and the related issues.

In #2631, we are introducing a new function getModelSchemaRef that can be used to obtain OpenAPI schema for a model in a configurable way. Example use:

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

Eventually, we plan to implement the following schema generator options:

• includeRelations in Allow controllers to provide definitions of models referenced in operation spec #2629
• partial in Emit schema with all model properties optional #2652
• exclude in Emit schema excluding certain model properties #2653

The current approach is very verbose. Compare the example above with a controller method that uses default options:

class TodoController {
  // ...

  @put('/todos/{id}', {
    responses: {
       // left out for brevity
    },
  })
  async replaceTodo(
    @param.path.number('id') id: number,
    @requestBody() todo: Todo,
  ): Promise<void> {
    await this.todoRepo.replaceById(id, todo);
  }
}

In this spike, we should research different options for simplifying request-body definitions requiring custom schema options.

Few examples to get started:

• In Partial update (PATCH) over REST #1722 (comment), @raymondfeng proposed:

  {
    schema: {
      'x-ts-type': Order,
      'x-ts-type-options': {
        partial: true,
        excludes: []
        }
    }

  This addresses only how to provide schema options when using x-ts-type extension. It does not address the problem of too complex spec required by @requestBody decorator.

• In Partial update (PATCH) over REST #1722 (comment), @bajtos proposed a different solution:

  class TodoController {
      // ...
  
      // `id` property is not allowed for `create`:
      @post('/')
      createTodo(@requestBody(Todo, {exclude: ['id']}) todo: ExcludeKeys<Todo, 'id'>) {}
  
      // all properties are allowed, all are optional
      @patch('/')
      updateTodo(@requestBody(Todo, {partial: true}) todo: Partial<Todo>) {}
  }

Acceptance criteria

• Read through prior discussions: Partial update (PATCH) over REST #1722, OpenAPI decorator does not properly generate schemas of type Partial #1179, fix: change service generator's ds to uppercase #2125, etc.
• Research different options for improving the current situation
• Open a spike pull request showing a PoC of the proposed implementation
• In the PR, include a /_SPIKE_.md document explaining what options you considered, what were pros and cons, how and why did you pick the winner. Include a list of follow-up stories needed to implement the proposed solution.
• Discuss the propsal with the team and get their approval
• Create follow-up stories.