feat(spec): allow defining custom media type of responses + fix(koa): dont overwrite content-type of response

[mrl5]

problem description: currently application/json is hardcoded into generated spec

proposed solution: allow specifying custom media type in generated spec
on both controller level by:

• using new @Produces decorator

and on method level by:

• using new @Produces decorator
• introducing new optional arg for @SuccessResponse decorator
• introducing new optional arg for @Response decorator
• setting Content-Type header in @Res decorator

impact:

• cli: controller generator
• cli: method generator
• cli: parameter generator
• cli: spec2 generator
• cli: spec3 generator
• runtime: response decorators

Closes #1126
Related #968

All Submissions:

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same update/change?
• Have you written unit tests?
• Have you written unit tests that cover the negative cases (i.e.: if bad data is submitted, does the library respond properly)?
• This PR is associated with an existing issue?

Closing issues

• Put closes #XXXX (where XXXX is the issue number) in your comment to auto-close the issue that your PR fixes.

If this is a new feature submission:

• Has the issue had a maintainer respond to the issue and clarify that the feature is something that aligns with the goals and philosophy of the project?

Potential Problems With The Approach

1. Someone could think that defining custom media type will also override content-type of actual response (which is not a case). However I don't think it's a problem -> if you check the issues from the past you will see that writing custom methods was encouraged - for example Send file / return raw binary "application/octect-stream" or "image/jpeg" ... #44 Return HTML from controller #224
2. OAS2 is not affected by this changes
3. I wasn't able to introduce new arg for setting custom media type for @Res decorator

Test plan

1. I've tried to show that it is possible to set @Produces on controller level
2. I've tried to show that even when @Produces is set on controller level it is possible to set it also for specific method
3. I've tried to show that OAS3 media type of responses is possible to be changed by passing new optional arg in @Response and @SuccessResponse decorators
4. I've tried to show that OAS3 media type of responses is possible to be changed by defining headers for @Res decorator

[github-actions]

Hello there mrl5 👋

Thank you and congrats 🎉 for opening your first PR on this project.✨

We will review the following PR soon! 👀

[dderevjanik]

@mrl5 very nice PR!
I'm just curious, what's the reason behind @MediaType decorator? I mean, most frameworks (jersey, spring, asp.net, nestjs, etc.) are using @Produces or @ProducesSomething wording - so you can distinguish between @Consumes.

In case that TSOA will support @Consumes in future, IMHO it could be confusing to have something like this in controller:

 @Get('process')
 @Consumes('image/png')  // Consumes MediaType
 @MediaType('text/plain') // Produces MediaType
  public async processImage(@Request() request: ExRequest): Promise<string> {
    // code
    return '';
  }

Instead of this

 @Get('process')
 @Consumes('image/png')  // Consumes MediaType
 @Produces('text/plain') // Produces MediaType
  public async processImage(@Request() request: ExRequest): Promise<string> {
    // code
    return '';
  }

[mrl5]

thanks for code review @dderevjanik - I agree that @Produces and @Consumes are more accurate. I will change that

I'm just curious, what's the reason behind @MediaType decorator?

I was inspired by the code snippets from #968

@WoH is it ok to git commit --amend not to produce commit flood on every improvement or you prefer to keep it separated?

[WoH]

Amending and rebasing is fine

[mrl5]

1. pushed improvements suggested by @WoH and @dderevjanik
2. updated PR description
3. added possibility to define @Produces on controller level

[mrl5]

pushed additional commit that:

1. fixes issue koa integration overwrites content-type of response #1134
2. introduces integration tests checking content-type

[WoH]

A list of MIME types the APIs can produce.
This is global to all APIs but can be overridden on specific API calls.
Value MUST be as described under Mime Types.

Maybe I'm interpreting too much, but we should be able to leave this as is, remove the todo and override on path.method.produces?

[mrl5]

1. amended with changes from code review
2. updated PR description

thanks @WoH for detailed CR :) I hope we're good to go now

[WoH]

Thanks for this PR and your patience during the review, much appreciated. Great Work!

[alberto-rubio]

Please, @mrl5 and @WoH, is this working in version 4.0.0-alpha.2? I'm adding the decorator:
@Produces('text/event-stream')
at method level, but it continues producing "application/json" in the generated openapi yaml definition.

Should I do any additional thing to see "text/event-stream" in the generate openapi?

Thanks and best regards!!

[mrl5]

hi @alberto-rubio - I think that this changes are already included in this version. It's hard to help you w/o seeing any example code that is producing unexpected results

if you need example you can study this file that is used in unit tests to ensure that feature introduced in this PR works:

tsoa/tests/fixtures/controllers/mediaTypeController.ts

Lines 27 to 29 in 6a289a7

	@Get('Custom/security.txt')
	@Produces('text/plain')
	public async getCustomProduces(): Promise<string> {