Syntactic sugar for requestBody() with custom schema options #3257

Suggestion

At the moment, it's cumbersome to describe a request-body parameter with a schema built from a model with custom options.

See e.g. #3199

class NoteController {
  // ...

  @patch('/notes/{id}', {
    responses: {
      '204': {
        description: 'Note PATCH success',
      },
    },
  })
  async updateById(
    @param.path.number('id') id: number,

    /*** LOOK AT THIS LONG BLOG OF CODE: ***/
    @requestBody({
      content: {
        'application/json': {
          schema: getModelSchemaRef(Note, {partial: true}),
        },
      },
    })
    /*** END ***/
    note: Partial<Note>,
  ): Promise<void> {
    await this.noteRepository.updateById(id, note);
  }
}

Let's find a more concise way how to describe such request bodies.

Examples

Few of many possible solutions:

1. New decorator

class NoteController {
  // ...

  @patch('/notes/{id}', {
    responses: {
      '204': {
        description: 'Note PATCH success',
      },
    },
  })
  async updateById(
    @param.path.number('id') id: number,

    @requestBodyWithSchema(getModelSchemaRef(Note, {partial: true}))
    note: Partial<Note>,
  ): Promise<void> {
    await this.noteRepository.updateById(id, note);
  }
}

2. New helper

class NoteController {
  // ...

  @patch('/notes/{id}', {
    responses: {
      '204': {
        description: 'Note PATCH success',
      },
    },
  })
  async updateById(
    @param.path.number('id') id: number,

    @requestBody(bodyFromSchema(getModelSchemaRef(Note, {partial: true})))
    note: Partial<Note>,
  ): Promise<void> {
    await this.noteRepository.updateById(id, note);
  }
}

Important considerations:

• We should keep the decorator decoupled from the helper generating the schema. This is important to allow interoperability with 3rd party ORMs like TypeORM and to keep it easy for users to provide a custom schema (e.g. hand-written, not generated).

• In the future, we may add support for parsing XML requests. Ideally, the new helper should be designed in such way to support that addition in the future, without any changes needed in the controller code. I.e. the new helper should not be tied to JSON content-type, but instead should be prepared to be extended by additional content-types like XML in the future.

The example snippets above meets both criteria.

Acceptance criteria

• Implement a new helper accepting a model schema and converting it into request-body definition
• Update all examples to use the new helper
• Update controller templates in CLI to use the new helper (don't forget about controllers for relations!)
• Update https://github.com/strongloop/loopback4-example-shopping to use the new helper too
• Update the documentation (code snippets, possibly other places too)