Feature suggestion: decorator for endpoint-specific OpenAPI overrides

[calvinwyoung]

Sorting

• I'm submitting a ...

  • [ ] bug report
  • [X] feature request
  • [ ] support request

• I confirm that I

  • [X] used the search to make sure that a similar issue hasn't already been submit

Detailed Description

Tsoa supports overwriting the generated swagger.json by specifying a custom spec in tsoa.json. This is currently the recommended solution for handling use cases like file uploads. The dowside of this approach is that it moves the OpenAPI configuration far away from the implementing code, which is exactly the problem that tsoa is trying to solve.

Would it be useful to have something like an @OpenApiOverride decorator that allows specifying the overriding configuration alongside the endpoint implementation? This would essentially provide a nicer escape hatch for implementing functionality that tsoa doesn't currently provide out-of-the-box. I acknowledge this could be viewed as either useful or atrocious.

How do the maintainers feel about this? If this is useful, I'd be happy to help with this effort.

[WoH]

I don't really like the spec merging as it is today, so I think we should pull that thread and see where it leads us. Haven't thought about the API and implications in detail (like what should or should not override other parts of the spec), but I'm intrigued.

[calvinwyoung]

Here's an idea to get the conversation started: the most naive solution would be to implement an @OpenApiOverride decorator that simply accepts the endpoint-specific overrides that should get merged into the generated spec. The file upload example could then be rewritten as:

  @Post('/files/uploadFile')
  @OpenApiOverride({
    "consumes": [
      "multipart/form-data"
    ],
    "parameters": [
      {
        "in": "formData",
        "name": "randomFileIsHere",
        "required": true,
        "type": "file"
      }
    ]
  })
  async uploadFile(...): Promise<...> {

  }

I assume the primary use case would be to augment the generated spec with parameters / options that tsoa doesn't currently handle out of the box. Therefore, I'd also assume the default behavior would be a deepmerge, but the decorator could also support an optional specMerging argument to allow the user to specify immediate or recursive.

The primary benefit is that it provides users with infinite customization for their individual endpoint. The primary downside is that it's kind of a hack, but still a less ugly hack than the current spec merging solution.

@WoH What's your take on this idea?