Tsoa: Support for relative `host` in openapi 3

[Eoksni]

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

Have in the output something like

    "servers": [
        {
            "url": "/v1"
        }
    ]

I'd like to be able to specify relative host, which is allowed by specification https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#fixed-fields-4.

Current Behavior

Currently if I omit host field in the swagger config or use empty "host": "", it gets replaced with http://localhost:3000. Using "host": "/" also doesn't work.

Possible Solution

Steps to Reproduce

Context (Environment)

Version of the library: 2.5.9
Version of NodeJS: 12

• Confirm you were using yarn not npm: [ ]

Detailed Description

Breaking change?

[jreusch-barco]

hey hey
actually we're also currently in need to have this feature.
i would volunteer to do a PR for this, perhaps we can agree on how to do it upfront?

as proposal:
1) just having localhost:3000 as a default does not seem reasonbale for me to be honest, how about in this case just using the "basePath"-only variant? (as this is valid in the spec anyway?
-> that would mean change the default -> considered breaking change?

2) have an additional option or put it as an option for the host config param to use only the path in
https://github.com/lukeautry/tsoa/blob/master/src/swagger/specGenerator3.ts#L97

[dgreene1]

@Eoksni and @jreusch-barco please share what the final resulting YAML would be based off of the configuration. Until I see that I am unclear.

[Eoksni]

@dgreene1 https://swagger.io/docs/specification/api-host-and-base-path/

servers:
  - url: /

or

servers:
  - url: /v1

if basePath is specified.

I personally agree with @jreusch-barco (1) option, making it default would be natural way to do this.

EDITED:
Btw, quote from the spec

If the servers array is not provided or is empty, the server URL defaults to /:

servers:
  - url: /

[jreusch-barco]

yep, yaml would look exactly like that, also confirmed that this works (e.g. in swagger-ui-express) by manually editing the schema file.

[Eoksni]

@dgreene1 If you don't want breaking change, I suggest host: '/' to behave as relative path because right now it outputs something meaningless anyway (http:/// is not a valid url as far as I know).

[jreusch-barco]

that also was one of my thoughts, but IMHO i find it rather unintuitive and not nice..

tbh: i would be interested when the default value (localhost:3000) does actually make sense.
changing the default here is maybe really the cleanest solution (and most likely will not break anything out there)

[dgreene1]

Maybe we can change the default in v3 (cc @WoH) but for now we’ll need a v2 solution that is backwards compatible. So I think the forward slash solution is fine. I believe that is how relative paths work in Node’s fs and path modules right? If not, we should adopt a relative path strategy that follows Node’s.

[Eoksni]

@dgreene1 In Node's fs and path / works as absolute path and ./ as relative. Personally I'm fine with both.

[dgreene1]

Okay (thank you for the reminder— I’ve been stuck working on C# last few months).

So yea, I think that there are only two valid options:
1) use ./ as a magic string that tsoa will use to create a relative path
2) have an additional flag like ”useRelativeHost”

It sounds like we’re leaning toward option 1. I’d accept a PR for either.

[dgreene1]

(Continued from above) Or a third option. If you’re looking to achieve this result from the OpenAPI documentation we could achieve it by specifying null

If host is not specified, it is assumed to be the same host where the API documentation is being served.

So in other words,

“host”: null

Again, I think I’d accept a PR for any of the three options above.

PLEASE COMMENT if you or anyone else is reading this and you really don’t like one of the options so we know to avoid that one. As a reminder the options are:
1) ”host”: “./“
2) ”useRelativeHost”: true
3) `”host”: null

With the obvious best answer being that we should create a breaking change in v3 that interprets any falsy host value as “the same host where the API documentation is being served.” That’s probably what tsoa should have done from the beginning (right?). Hindsight is always 20/20.

[Eoksni]

I vote for host: null.

[jreusch-barco]

also
host: null
we have to go for a "not nice solution", that's the cleanest one of them IMHO.

one additional request:
if "useRelativeHost" will be the agreement, please lets reconsider the name. it's not the host which is relative, is it?

[dgreene1]

Thanks @jreusch-barco for submitting the v2 PR. I have a few minor requests there. And @Eoksni, I made a new issue for the "nice solution" which I have put in our v3 release bucket: https://github.com/lukeautry/tsoa/issues/555