Tsoa: Support for response headers in generated OpenAPI spec

[rhietala]

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

Expected Behavior

Using this kind of controller

interface ResponseHeaders {
  /**
   * Pagination uses Link header as defined in RFC5988
   */
  Link: string;
}

@Route("/")
export class FooController extends Controller {
  @Get()
  @SuccessHeaders<ResponseHeaders>()
  public async get(
    @Res() failed: TsoaResponse<400, string, ResponseHeaders>
  ): Promise<number> {
    if (false) {
      failed(400, "failure", { Link: "" });
    } else {
      this.setHeader("Link", '<https://localhost:3000/?page=2>; rel="next"');
      return 1;
    }
  }
}

It would be nice if the generated OpenAPI specification would have specifications for the response headers as well (as per https://swagger.io/specification/#response-object):

"paths": {
  "/": {
    "get": {
      "operationId": "Get",
      "responses": {
        "200": {
          "description": "Ok",
          "content": {
            "application/json": {
              "schema": {
                "type": "number",
                "format": "double"
              }
            }
          },
          "headers": {
            "Link": {
              "description": "Pagination uses Link header as defined in RFC5988",
              "schema": {
                "type": "string"
              }
            }
          }
        },
        "400": {
          "description": "",
          "content": {
            "application/json": {
              "schema": {
                "type": "string"
              }
            }
          },
          "headers": {
            "Link": {
              "description": "Pagination uses Link header as defined in RFC5988",
              "schema": {
                "type": "string"
              }
            }
          }
        }
      },
      "security": [],
      "parameters": []
    }
  }
},

I presumed @SuccessHeaders is an upcoming feature from #723.

Also, in real life it doesn't make sense to include the link header in error response, but I included it here just to illustrate that TsoaResponse should have the same functionality.

Current Behavior

Currently the generated specification has only the content schemas:

"paths": {
  "/": {
    "get": {
      "operationId": "Get",
      "responses": {
        "200": {
          "description": "Ok",
          "content": {
            "application/json": {
              "schema": {
                "type": "number",
                "format": "double"
              }
            }
          }
        },
        "400": {
          "description": "",
          "content": {
            "application/json": {
              "schema": {
                "type": "string"
              }
            }
          }
        }
      },
      "security": [],
      "parameters": []
    }
  }
},

Possible Solution

Steps to Reproduce

Working example repository https://github.com/rhietala/tsoa-response-header

Context (Environment)

Version of the library: 3.2.1
Version of NodeJS: 12.18.3

• Confirm you were using yarn not npm: [x]

Detailed Description

Breaking change?

Probably not for @SuccessHeaders as is not in 3.x? For TsoaResponse probably not either, as this would only add the optional descriptions and spec generation as a new feature, but I don't know.

[WoH]

I'd really like to have this in tsoa aswell. If you can open a PR I'd like to have a look.