Route Decorators

Route decorators are used to expose controller methods as REST API operations.If you are not familiar with the concept of Route or Controller, please seeLoopBack Route and LoopBack Controller to learnmore about them.

By calling a route decorator, you provide OpenAPI specification to describe theendpoint which the decorated method maps to. You can choose different decoratorsaccordingly or do a composition of them:

API Decorator

Syntax:@api(spec: ControllerSpec)

@api is a decorator for the controller class and is appended just before it’sdeclared. @api is used when you have multiplePaths Objectsthat contain all path definitions of your controller. Please note the api specsdefined with @api will override other api specs defined inside the controller.For example:

  1. @api({
  2.   basePath: '/',
  3.   paths: {
  4.     '/greet': {
  5.       get: {
  6.         'x-operation-name': 'greet',
  7.         'x-controller-name': 'MyController',
  8.         parameters: [{name: 'name', schema: {type: 'string'}, in: 'query'}],
  9.         responses: {
  10.           '200': {
  11.             description: 'greeting text',
  12.             content: {
  13.               'application/json': {
  14.                 schema: {type: 'string'},
  15.               },
  16.             },
  17.           },
  18.         },
  19.       },
  20.     },
  21.   },
  22. })
  23. class MyController {
  24.   // The operation endpoint defined here will be overriden!
  25.   @get('/greet')
  26.   greet(@param.query.number('limit') name: string) {}
  27. }
  28. app.controller(MyController);

A more detailed explanation can be found inSpecifying Controller APIs

Operation Decorator

Syntax:@operation(verb: string, path: string, spec?: OperationObject)

@operation is a controller method decorator. It exposes a Controller method asa REST API operation and is represented in the OpenAPI spec as anOperation Object.You can specify the verb, path, parameters, and response as a specification ofyour endpoint, for example:

  1. const spec = {
  2.   parameters: [{name: 'name', schema: {type: 'string'}, in: 'query'}],
  3.   responses: {
  4.     '200': {
  5.       description: 'greeting text',
  6.       content: {
  7.         'application/json': {
  8.           schema: {type: 'boolean'},
  9.         },
  10.       },
  11.     },
  12.   },
  13. };
  14. class MyController {
  15.   @operation('HEAD', '/checkExist', spec)
  16.   checkExist(name: string) {}
  17. }

Commonly-used Operation Decorators

Syntax:@get(path: string, spec?: OperationObject)

Same Syntax for decorators@post ,@put ,@patch ,@del

You can call these sugar operation decorators as a shortcut of @operation. Forexample:

  1. class MyController {
  2.   @get('/greet', spec)
  3.   greet(name: string) {}
  4. }

is equivalent to

  1. class MyController {
  2.   @operation('GET', '/greet', spec)
  3.   greet(name: string) {}
  4. }

Parameter Decorator

Syntax: seeAPI documentation

@param is applied to controller method parameters to generate an OpenAPIparameter specification for them.

For example:

  1. import {get, param} from '@loopback/rest';
  3. const categorySpec = {
  4.   name: 'category',
  5.   in: 'path',
  6.   required: true,
  7.   schema: {type: 'string'},
  8. };
  10. const pageSizeSpec = {
  11.   name: 'pageSize',
  12.   in: 'query',
  13.   required: false,
  14.   schema: {type: 'integer', format: 'int32'},
  15. };
  17. class MyController {
  18.   @get('Pets/{category}')
  19.   list(
  20.     @param(categorySpec) category: string,
  21.     @param(pageSizeSpec) pageSize?: number,
  22.   ) {}
  23. }

Writing the whole parameter specification is tedious, so we’ve created shortcutsto define the params with the pattern @param.${in}.${type}(${name}):

  • in: The parameter location. It can be one of the following values: query,header, or path.
  • type: Acommon name of OpenAPI primitive data type.
  • name: Name of the parameter. It should be a string.A list of available shortcuts for query can be found inAPI document,along with the shortcuts for path and header.

An equivalent example using the shortcut decorator would be:

  1. class MyController {
  2.   @get('/Pets/{category}')
  3.   list(
  4.     @param.path.string('category') category: string,
  5.     @param.query.number('pageSizes') pageSize?: number,
  6.   ) {}
  7. }

You can find specific use cases inWriting Controller methods

The parameter location cookie is not supported yet, see__(https://github.com/strongloop/loopback-next/issues/997)

RequestBody Decorator

Syntax: seeAPI documentation

@requestBody() is applied to a controller method parameter to generate OpenAPIrequestBody specification for it.

Only one parameter can be decorated by @requestBody per controller method.

A typicalOpenAPI requestBody specificationcontains properties description, required, and content:

  1. requestBodySpec: {
  2.   description: 'a user',
  3.   required: true,
  4.   content: {
  5.     'application/json': {...schemaSpec},
  6.     'application/text': {...schemaSpec},
  7.   },
  8. }

In order to use @requestBody in a parameter type, the model in the parametertype must be decorated with @model and @property:

  1. import {model, property} from '@loopback/repository';
  2. import {Address} from './address.model';
  4. @model()
  5. class User {
  6.   @property()
  7.   firstname: string;
  8.   @property()
  9.   lastname: string;
  10.   @property()
  11.   address: Address;
  12. }

To learn more about decorating models and the corresponding OpenAPI schema, seemodel decorators.

The model decorators allow type information of the model to be visible to thespec generator so that @requestBody can be used on the parameter:

/src/controllers/user.controller.ts

  1. import {User} from '../models/user.model';
  2. import {put} from '@loopback/rest';
  4. class UserController {
  5.   @put('/Users/{id}')
  6.   async replaceUser(
  7.     @param.path.string('id') id: string,
  8.     @requestBody() user: User,
  9.   ) {}
  10. }

For the simplest use case, you can leave the input of @requestBody empty sincewe automatically detect the type of user and generate the corresponding schemafor it. The default content type is set to be application/json.

You can also customize the generated requestBody specification in three ways:

  • Add the optional fields description and required
  1. class MyController {
  2.   @put('/Users/{id}')
  3.   async replaceUser(
  4.     @param.path.string('id') id: string,
  5.     @requestBody({
  6.       description: 'a modified user',
  7.       required: true,
  8.     })
  9.     user: User,
  10.   ) {}
  11. }
  • Override the content type or define multiple content types
  1. class MyController {
  2.   @put('/Users/{id}')
  3.   async replaceUser(
  4.     @param.path.string('id') id: string,
  5.     @requestBody({
  6.       content: {
  7.         // leave the schema as empty object, the decorator will generate it for both.
  8.         'application/text': {},
  9.         'application/xml': {},
  10.       },
  11.     })
  12.     user: User,
  13.   ) {}
  14. }
  • Override the schema specification
  1. import {UserSchema, User} from '../model/user.schema';
  3. class MyController {
  4.   @put('/Users/{id}')
  5.   async replaceUser(
  6.     @param.path.string('id') id: string,
  7.     @requestBody({
  8.       content: {
  9.         'application/json': UserSchema,
  10.       },
  11.     })
  12.     user: User,
  13.   ) {}
  14. }

We plan to support more @requestBody shortcuts in the future. You can trackthe feature instory 1064.

x-ts-type extension

To simplify schema definition and reference, LoopBack allows x-ts-typeextension for the OpenAPI schema object. The x-ts-type points to a model classor simple types. It can be used for parameters, request body and responses. Forexample,

  1. import {model, property} from '@loopback/repository';
  2. import {requestBody, post, get} from '@loopback/openapi-v3';
  4. @model()
  5. class MyModel {
  6.   @property()
  7.   name: string;
  8. }
  10. export class MyController {
  11.   @get('/', {
  12.     responses: {
  13.       '200': {
  14.         description: 'hello world',
  15.         content: {'application/json': {schema: {'x-ts-type': MyModel}}},
  16.       },
  17.     },
  18.   })
  19.   hello() {
  20.     return 'hello world';
  21.   }
  23.   @post('/')
  24.   greet(
  25.     @requestBody({
  26.       content: {'application/json': {schema: {'x-ts-type': MyModel}}},
  27.     })
  28.     body: MyModel,
  29.   ) {
  30.     return `hello ${body.name}`;
  31.   }
  32. }

The x-ts-type can be used for array and object properties too:

  1. const schemaWithArrayOfMyModel = {
  2.   type: 'array',
  3.   items: {
  4.     'x-ts-type': MyModel,
  5.   },
  6. };
  8. const schemaDeepArrayOfMyModel = {
  9.   type: 'array',
  10.   items: {
  11.     type: 'array',
  12.     items: {
  13.       'x-ts-type': MyModel,
  14.     },
  15.   },
  16. };
  18. const schemaWithObjectPropOfMyModel = {
  19.   type: 'object',
  20.   properties: {
  21.     myModel: {
  22.       'x-ts-type': MyModel,
  23.     },
  24.   },
  25. };
  27. export class SomeController {
  28.   @post('/my-controller')
  29.   greetObjectProperty(@requestBody({
  30.     content: {'application/json': {schema: schemaWithObjectPropOfMyModel}},
  31.   })
  32.   body: {
  33.     myModel: MyModel;
  34.   }): string {
  35.     return `hello ${body.myModel.name}!`;
  36.   }
  38.   @get('/my-controllers', {
  39.     responses: {
  40.       '200': {
  41.         description: 'hello world',
  42.         content: {'application/json': {schema: schemaWithArrayOfMyModel}},
  43.       },
  44.     },
  45.   })
  46.   everyone(): MyModel[] {
  47.     return [{name: 'blue'}, {name: 'red'}];
  48.   }
  50.   @post('/my-controllers')
  51.   greetEveryone(
  52.     @requestBody({
  53.       content: {'application/json': {schema: schemaDeepArrayOfMyModel}},
  54.     })
  55.     body: MyModel[][],
  56.   ): string {
  57.     return `hello ${body.map(objs => objs.map(m => m.name))}`;
  58.   }
  59. }

When the OpenAPI spec is generated, the xs-ts-type is mapped to{$ref: '#/components/schemas/MyModel'} and a corresponding schema is added tocomponents.schemas.MyModel of the spec.