Spike: simplify requestBody annotation with schema options

[bajtos]

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.

[jannyHou]

Update:

According to requestBody spec, different content types could have different schemas, this is why taking a single type and its options like

@post('/') createTodo(@requestBody(Todo, {exclude: ['id']}) todo: ExcludeKeys<Todo, 'id'>) {}

could not handle more complicated cases, even though it's the concisest signature.

The other proposal

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

looks more declarative than calling getModelSchemaRef(TodoList, {partial: true}), directly, but

It does not address the problem of too complex spec required by @requestBody decorator.

is still valid.

So I am proposing create some sugar apis like @requestBody().addContent('media-content-type-name', ModelCtor, options) to simplify the UX. And will try implement it in code.

[jannyHou]

The PoC of new proposal is created in draft PR #3466

Follow up stories see:

• [Spike/Discussion] The proposal of the new requestBody decorator #3493
• Improve the @requestBody  #3496
• [Refactor] Update controllers' CRUD functions in example packages #3497