Sugar `response` decorators for easier controller config

[virkt25]

Description / Steps to reproduce / Feature proposal

Currently an OpenAPI response can only be set by providing the complete controller spec OR by passing it in the operation decorator. Describing a spec is very tedious and time consuming and we should provide an easier way to automagically assemble the spec.

Proposed Design

class MyController {
  @response.ok('todo model instance created')
  @post('/')
  myMethod(): Promise<Todo> {
    // implementation
  }
}

A few alternatives for the decorator:

// schema in this case can be a Model / TypeScript Type.
@response(statusCode: number, description: string, responseSchema: schema)
@response.ok(description: string, responseSchema: schema) // ok in this case would translate to a 200
@response.statusCode(description: string, responseSchema: schema) // statusCode being 200, 404, etc.
@response.ok(description: string) + @response.schema(Todo) // allows arbitrary schema registration with the OpenAPI spec.

---

Acceptance Criteria

• Create a series of new "sugar" decorators to simplify OpenAPI response decorations for REST APIs. Proposed Decorators are as follows:

@response(200, 'description', 'application/custom-type', Customer)
@response(statusCode, Customer)
@response(statusCode, description, Customer)
@response(Customer) // Automagically generate statusCode, description (as done today), and assume json return type
// NOTE: Document that complex cases are dealt with via the operational decorators (@get, @post). 

• The decorators should be "stackable", meaning the same decorator can be utilized multiple times on the same class method to specify multiple responses

class MyController {
@response(String)
@response(500, 'server error', Error)
hello() { // ... }
}

• Update CLI controller templates to use the new decorator instead
• Update example/todo, example/todo-list to use the new decorators
• Tests
• Docs
• Blog

[bajtos]

@response.statusCode(description: string, responseSchema: schema) // statusCode being 200, 404, etc.

Can we perhaps use status names from http-errors package? E.g. @response.notFound, @response.internalServerError, etc.

[virkt25]

For sure! I think the only thing would be that I would be is should the response name be capitalized as that is how it is in http-errors? Ex: @response.NotFound, @response.InternalServerError, etc.

[raymondfeng]

It can be as simple as @response(statusCode: number, schema: SchemaObject | ReferenceObject, description='').

For example:

@response(200, {x-ts-type: Customer})
@response(400, {x-ts-type: InvalidCustomerError}, 'customer name is missing')

[virkt25]

That certainly works ... I think we can go further and just let the user pass in the type directly instead of wrapping it in an Object with the x-ts-type property. Only thing I see missing is how does a user set the content-type? Default can be application/json but if a user wanted to change it what do we do?

[bajtos]

That certainly works ... I think we can go further and just let the user pass in the type directly instead of wrapping it in an Object with the x-ts-type property.

Yes please! We can always add support for arbitrary schema later, because it's easy to distinguish between as schema object ({'x-ts-type': Product}) a model constructor function (Product).

Only thing I see missing is how does a user set the content-type? Default can be application/json but if a user wanted to change it what do we do?

How about the following:

@response.json(200, Customer);
// later we can add
@response.xml(200, Customer);
@response.custom('application/custom-type', 200, Customer);

@response(statusCode: number, schema: SchemaObject | ReferenceObject, description='')

In the future, we may want to allow users to pass arbitrary extra properties besides description, e.g. {description: 'lorem ipsum', x-my-extension: true}. This can be easily supported later by using string | object type for the last parameter, so nothing to worry about right now.

[bajtos]

Another option I was pondering recently was to use a Builder pattern.

@response(200).json().model(Customer).description('lorem ipsum')
@response(404).contentType('application/custom-type').schema(MySchema)

I think this can be particularly useful for parameter decorators, where we already have M times N functions, where M is the number of in values (query, path, etc.) and M is the number of types (string, integer, etc.). To distinguish between optional and required parameters, we would have to create another set of M times N functions. That does not scale well.

The builder pattern has two challenges:

• The decorator has to return something that's both a callable decorator function that TypeScript can use AND has builder methods for further chaining.
• Extensibility - how to allow 3rd-party extensions to contribute custom builder methods together with type information needed for TypeScript to verify correct usage.

[bajtos]

I think the only thing would be that I would be is should the response name be capitalized as that is how it is in http-errors? Ex: @response.NotFound, @response.InternalServerError, etc.

I find the style @response.NotFound rather inconsistent to be honest. I am sure it is fairly easy to convert from NotFound to notFound, unless I am missing something?

[virkt25]

description is a required property of the response object while the return type is optional. I think the following would be a good start.

@response.json(200, 'description', Customer); // Sugar on `@response`
@response.xml(200, 'description', Customer);  // Sugar on `@response`
@response('application/custom-type', 200, 'description', Customer)

I like the statusCode being the first argument but at the same time think it'd be better if it was optional / defaulted to 200 as that's most likely the only response a user will describe at a minimum.

@response.json('description', Customer)

[bajtos]

@response.json('description', Customer)

I love that form ☝️

@response('application/custom-type', 200, 'description', Customer)

Maybe put the code first and the content-type second? That's how the information is mapped in the spec IIRC and send down the TCP/IP socket in the HTTP response.

@response(200, 'application/custom-type', 'description', Customer)

[virkt25]

Maybe put the code first and the content-type second? That's how the information is mapped in the spec IIRC and send down the TCP/IP socket in the HTTP response.

That makes sense to me. +1 for the the @response decorator signature proposed as well -- I would just like the statusCode to default to 200 if not present for all the @response decorators.

[jannyHou]

• To handle multiple descriptions for the same status code: The story owner can drive a discussion regarding how to generate the description: pick the first one or join them, etc... and document it.
• The simplest decorator would be omitting the status code and content type, only has description(optional) and model type.