[QUESTION] @Returns decorator from (@tsed/schema) oneOf merging problem.

[DKorosec]

Hello 👋

I've a question about usage of @Returns decorator in conjunction with other decorators that define their own return models

Directly using the Returns decorator it's really simple to define exact or oneOf schema without any problems:

...
@Returns(200, Model)
@Returns(400, [ErrorModel1, ErrorModel2])
async endpointMethod() {...}

Then I've added a decorator for custom authentication which uses specific middleware to handle authentication logic. Where I've used the following pattern to inject middleware's response error model (so I don't need to write that on every endpoint that uses this decorator):

export function Authenticated(): Function {
  return useDecorators(
    UseAuth(BearerAuthMiddleware),
    Security("BearerAuth"),
    Returns(401, UnauthenticatedErrorModel));
}

Now the initial endpoint looks like this and still works as expected (spec defines 200, 400 and 401 error models correctly)...

...
@Authenticated()
@Returns(200, Model)
@Returns(400, [ErrorModel1, ErrorModel2])
async endpointMethod() {...}

... but let's say the endpointMethod() starts using another service which now makes this endpoint method return additional and different 401 ErrorModel.
Thus we'll annotate it and get:

...
@Authenticated()
@Returns(200, Model)
@Returns(400, [ErrorModel1, ErrorModel2])
@Returns(401, ServiceErrorModel);
async endpointMethod() {...}

And at that moment we now have two models that are related to the same http status code (ServiceErrorModel and UnauthenticatedErrorModel) which aren't passed into Returns decorator as an array but separately, and that causes only one to appear in the final schema.

So my question is, is there a way to solve this (how to make final schema use oneOf for ServiceErrorModel and UnauthenticatedErrorModel)? If so, I would really appreciate an example 🙏.

[Romakita]

Returns(400, [ErrorModel1, ErrorModel2]) Isn’t correct.

try Returns(400).OneOf(ErrorModel1, ErrorModel2)

[DKorosec]

Just tried, sadly it doesn't solve the issue mentioned. Now I also get a wrong schema describing "GenericError" model, and no sign of ErrorModel1 or ErrorModel2.

[DKorosec]

Here is the minimal example to reproduce what i'm trying to say (and trying to merge 😅):

import { Get, Required, Returns, Security } from "@tsed/schema";
import { Controller, Middleware, MiddlewareMethods, UseAuth } from "@tsed/common";
import { useDecorators } from "@tsed/core";

class Model1 { @Required() model1: string; }
class Model2 { @Required() model2: string; }
class Model3 { @Required() model3: string; }

@Middleware()
class AuthMiddleware implements MiddlewareMethods {
  public async use(): Promise<void> { }
}

function Authenticated(): Function {
  return useDecorators(UseAuth(AuthMiddleware), Security("BearerAuth"), Returns(401, Model2));
}

@Controller("/auth")
export class AuthController {
  @Get("/")
  @Authenticated()
  @Returns(200, Model1)
  @Returns(401, Model3) // **this one gets "lost" as a side effect of included @Authenticated overriding it.**
  get() { }
}

[Romakita]

Hello @DKorosec

I said:

• Returns(401, [ErrorModel1, ErrorModel2]) Isn’t correct. I never written that in the documentation, I don't know where you have find it
• Returns doesn't append model for the same code.
• Decorators order are importante

So based on these rules you a limited options:

• Remove @Returns used in @Authenticated decorator and use @Returns(401).OneOf(Model1, Model2, Model3)
• Extend the Authenticated signature to give a list of models like that: @Authorize({'401': [Model1, Model2, Model3]}) (and please use .OneOf in this case)

Choose your preferred solution ;)

See you

[DKorosec]

Sorry to bother @Romakita but using the @Returns(401).OneOf(Model1, Model2, Model3) pattern doesnt generate correct spec for me (as I have mentioned in my first reply). I get the following result:

Where if I use the "deprecated/incorrect" interface @Returns(401, [Model1, Model2, Model3]) I get correct result:

Is there anything I need to do with the models for them to display as is?

[Romakita]

ha sorry @DKorosec. I was pretty sure that oneOf should work as expected. I'm going to do a quick test.

[Romakita]

My bad, I given you the wrong code example.

The returns decorator apply by default the 401 Unauthorize model if there is no second parameters. So to fix that, gives Object as second parameters to avoid the default behavior:

@Returns(401, Object).OneOf(ClassA, ClassB)

[Romakita]

      class Controller {
        @Returns(401, Object).OneOf(ClassA, ClassB)
        @OperationPath("GET", "/")
        method() {
        }
      }

      const spec = getSpec(Controller, {specType: SpecTypes.OPENAPI}) as Partial<OpenSpec3>;

      expect(spec.paths!["/"].get!.responses["401"]).toEqual({
        "content": {
          "application/json": {
            "schema": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/ClassA"
                },
                {
                  "$ref": "#/components/schemas/ClassB"
                }
              ]
            }
          }
        },
        "description": "Unauthorized"
      });

[DKorosec]

@Romakita it works, thank you!!!

I've applied your change to my custom decorator "ReturnsStored" and it also works with "merging" the models based on the status code even if they are included inside other decorators for instance Authenticated (which was my initial requests). 🥳

Here is the final solution if ever anybody stumbles across the same problem:

function ReturnsStored(code: number, ...modelsIn: Array<new () => any>) {
  return (target: Object, propertyKey: string, descriptor: PropertyDescriptor) => {
    const responses = initStoreKey(Store.fromMethod(target, propertyKey), 'returns');
    const models = responses[code] ??= [];
    models.push(...modelsIn);
    if (models.length === 1) {
      Returns(code, models[0])(target, propertyKey, descriptor);
    } else {
      Returns(code, Object).OneOf(...models)(target, propertyKey, descriptor);
    }
  }
}

function Authenticated(): Function {
    return useDecorators(
      UseAuth(AuthMiddleware),
      Security("BearerAuth"),
      ReturnsStored(401, Model2)
    );
}

@Controller("/auth")
export class AuthController {
  @Get("/")
  @Authenticated()
  @ReturnsStored(200, Model1)
  @ReturnsStored(401, Model3) 
  get() { }
}

produces (irrelevant to decorator order now):

"/auth": {
      "get": {
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Model1"
                }
              }
            },
            "description": "Success"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Model3"
                    },
                    {
                      "$ref": "#/components/schemas/Model2"
                    }
                  ]
                }
              }
            },
            "description": "Unauthorized"
          }
        },
        ....

Thanks again! 👋