Add support for refAlias as a "ValidHeader" and numbers as valid header values

[efrenaguilar95]

Add support for refAlias as a "ValidHeader"

I would like to add support for refAlias types as "ValidHeader" types. This will help solve some issues I have run into when using the @response decorator as well as some other potential use cases that use this type.

I would also like to add support for numbers as keys within "ValidHeader" types. This is a quick fix so not documenting that here, but can if people really want it.

I already have some code changes made to implement this, making this issue since it was asked for in the Contribution guide.

Current Behavior

Currently, in order to get a valid spec generated for a response's headers this format needs to be created.

"404":
  headers:
    X-RateLimit-Used:
      schema:
        type: number
        format: integer
      required: true
    X-RateLimit-Remaining:
      schema:
        type: number
        format: integer
      required: true

However, the only way to do this (that I have found) with the @response header is to do this.

@Response<NotFoundJSON, {
  "X-Rate-Limit-Used": number;
  "X-RateLimit-Remaining": number;
}>(
  responseCodes.NOT_FOUND, 
  "Given when the requested data is not found".
)

Which is fine, but gets very messy once a lot of Responses are needed. (Pretend these are all different response codes)

@Response<NotFoundJSON, {
  "X-Rate-Limit-Used": number;
  "X-RateLimit-Remaining": number;
}>(
  responseCodes.NOT_FOUND, 
  "Given when the requested data is not found".
)
@Response<NotFoundJSON, {
  "X-Rate-Limit-Used": number;
  "X-RateLimit-Remaining": number;
}>(
  responseCodes.NOT_FOUND, 
  "Given when the requested data is not found".
)
@Response<NotFoundJSON, {
  "X-Rate-Limit-Used": number;
  "X-RateLimit-Remaining": number;
}>(
  responseCodes.NOT_FOUND, 
  "Given when the requested data is not found".
)
@Response<NotFoundJSON, {
  "X-Rate-Limit-Used": number;
  "X-RateLimit-Remaining": number;
}>(
  responseCodes.NOT_FOUND, 
  "Given when the requested data is not found".
)
@Response<NotFoundJSON, {
  "X-Rate-Limit-Used": number;
  "X-RateLimit-Remaining": number;
}>(
  responseCodes.NOT_FOUND, 
  "Given when the requested data is not found".
)

I tried defining as an interface, but the generator does not match the format correctly.

e.g.

interface rateLimitHeaderInterface{
  "X-Rate-Limit-Used": number;
  "X-RateLimit-Remaining": number;
}

@Response<NotFoundJSON, rateLimitHeaderInterface>(
  responseCodes.NOT_FOUND, 
  "Given when the requested data is not found".
)

yields

"429":
  headers:
    rateLimitHeaderInterface:
      schema:
        $ref: "#/components/schemas/rateLimitHeaderInterface"

Desired Behavior

However using types does work and solve this problem. The only issue is that "refAliases" are currently not supported due to some logic in the source code.

type rateLimitHeaderType = {
  "X-Rate-Limit-Used": number;
  "X-RateLimit-Remaining": number;
}

@Response<NotFoundJSON, rateLimitHeaderType>(
  responseCodes.NOT_FOUND, 
  "Given when the requested data is not found".
)

Yields

"404":
  headers:
    X-RateLimit-Used:
      schema:
        type: number
        format: integer
      required: true
    X-RateLimit-Remaining:
      schema:
        type: number
        format: integer
      required: true

I have tested this by modifying some of the source code and it works great. Mainly making this issue since it said an issue was required for creating a contribution.

Background

The reason this even came up was because I am using OWAS TOP 10 spectral definitions to follow good security guidelines. One of their requirements is for certain headers, such as rate-limiting to be set. And they require the formatting I have mentioned above.

Not too familiar with header formatting on OpenAPI, but from what I have found, this does look like the norm. Not sure if this calls for an update to how @response handles the header input, or maybe I shouldn't be using @response for these header definitions. Either way, hope to make a PR for this as soon as I get the OK :)

[github-actions]

Hello there efrenaguilar95 👋

Thank you for opening your very first issue in this project.

We will try to get back to you as soon as we can.👀