Syntactic sugar for requestBody() with custom schema options

[bajtos]

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)

[bajtos]

Related:

• spike [SPIKE] feat: simplify request body decorator #3398
• another spike Spike/new requestbody #3466
• Improve the @requestBody Improve the @requestBody  #3496
• [Refactor] Update controllers' CRUD functions in example packages [Refactor] Update controllers' CRUD functions in example packages #3497

[stale]

This issue has been marked stale because it has not seen activity within six months. If you believe this to be in error, please contact one of the code owners, listed in the CODEOWNERS file at the top-level of this repository. This issue will be closed within 30 days of being stale.

[stale]

This issue has been closed due to continued inactivity. Thank you for your understanding. If you believe this to be in error, please contact one of the code owners, listed in the CODEOWNERS file at the top-level of this repository.