Support for multiple servers information

[deividfortuna]

Sorting

• I'm submitting a ...

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

• I confirm that I

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

Expected Behavior

servers:
  - url: https://api.example.com/v1
    description: Production server (uses live data)
  - url: https://sandbox-api.example.com:8443/v1
    description: Sandbox server (uses test data)

Current Behavior

servers:
  - url: https://api.example.com/v1 

Possible Solution

  private buildServers() {
    if (Array.isArray(this.config.host)) {
      return this.config.host.map(host => this.buildServer(host));
    } else {
      return [this.buildServer({ host: this.config.host })];
    }
  }

  private buildServer(serverConfig: { host?: string; description?: string }): Swagger.Server {
    const basePath = normalisePath(this.config.basePath as string, '/', undefined, false);
    const scheme = this.config.schemes ? this.config.schemes[0] : 'https';
    const url = serverConfig.host ? `${scheme}://${serverConfig.host}${basePath}` : basePath;

    const server = {
      url,
    } as Swagger.Server;

    if (serverConfig.description) {
      server.description = serverConfig.description;
    }

    return server;
  }

Context (Environment)

Version of the library: 3.0.8 Version of NodeJS: v12.16.3

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

Detailed Description

OpenApi3 supports multiples servers information and that can be useful to be used swagger pointing to multiple environments.

Breaking change?

The solution is a workaround to a breaking change.

[WoH]

There is an abandoned PR here. As I said in the review, we should support host (for backwards compat), but allow OpenAPI 3 to define a servers?: OpenAPIServer[] config setting.

[deividfortuna]

Thanks for reply @WoH, I'm keen to move the PR # #633 forward if it is the case. My solution also support host configuration as a string but if it is an array will treat as multiples host configuration. I do have the changes on my machine not sure if I should open another PR, it is lacking corner cases coverage at this moment.

export interface Spec2 extends Spec {
    swagger: '2.0';
    host?: string | Array<Host>;
...

  export interface Host {
    host: string;
    description?: string;
  }

[WoH]

What would you do in case specVersion: 2 and hosts is an Array<Host>? Warn and take the first one's host? My worry here is that both formats are very different (host: string vs. servers: {url: string, description: string}[] and I don't know if I'd want to handle all that translation.

[deividfortuna]

Thanks @WoH, it make sense. I'll take a look in the #633 and see what I can do to help move forward.

[DroidGar]

its any workaround in mid time?

[Dynasty9]

Workaround: Below I used the spec.spec override to get my servers in there.

// tsoa.json
	"spec": {
		"specVersion": 3,
		"basePath": "/api/v1",
		"spec": { // Override the servers section
			"servers": [
				{
					"url": "http://localhost:8080/api/v1",
					"description": "Local development"
				},
				{
					"url": "http://prod:8080/api/v1",
					"description": "Prod development"
				}
			]
		},
	},

Resulting in the final

// swagger.json
  {
   ... 
  "servers": [
    {
      "url": "http://localhost:8080/api/v1",
      "description": "Local development"
    },
    {
      "url": "http://prod:8080/api/v1",
      "description": "Prod development"
    }
  ]```

[karlismelderis]

also let's open option to specify http/https if server is localhost I don't think anyone expects to run under SSL

[guhyeon]

Hmm... This is a bit off topic, how did you do api versioning with tsoa?