Allow using any of the listed servers in api docu/spec

[embix]

We currently have a service returning multiple servers

servers:
  - url: https://staging.api.company.com
    description: staging (always requires auth)
  - url: https://localhost:5001/
    description: local dev/test server with tls
  - url: http://localhost:5000/
    description: local dev/test server

If I connect to localhost:5001 it retrieves the swagger/openapi and uses staging instead of the instance wanted to connected to. It seems like httprepl always uses the first server. Is there any way we can make it use another one?

[tlmii]

If you specify the base url explicitly in the connect command (using the --base option in addition to the other arguments and options you were specifying) that will force the tool to accept that as your base and ignore what is specified in the servers array in the OpenAPI description document.

That said, we should probably go ahead and add the ability to do that some other way - by index during connect or by another command after connect has occurred.

[tlmii]

@bradygaster This is something I'd be curious about your thoughts on from a UX perspective - since the servers are only identified by a url (and implicitly by index), what would be the correct experience for a user to specify? It sort of seems like the --base is already the right experience, though maybe we need to bring back the set base command in another form to be able to switch between servers quickly.

Thoughts?

[bradygaster]

Curious what @embix would say if we implied his YAML island above required a tag-like property that would make it easier. Sure, set base would be good as a bring-back, but I wonder if @embix or others would like the idea of having an API with multiple environments (localhost, dev, staging, qa, etc.) that they could test using something like a switch. So maybe we extend on @embix's YAML from above:

servers:
  - url: https://staging.api.company.com
    description: staging (always requires auth)
  - url: https://localhost:5001/
    description: local dev/test server with tls
  - url: http://localhost:5000/
    description: local dev/test server

... and turn it into something like this?

environments:
  - url: https://staging.api.company.com
    description: staging (always requires auth)
    tag: staging
  - url: https://localhost:5001/
    description: local dev/test server with tls
    tag: localhost-https
  - url: http://localhost:5000/
    description: local dev/test server
    tag: localhost

Would we want to extend it further to enable multiple-API support? Something like:

apis:
  name: products
    environments:
      - url: https://staging.api.company.com
        description: staging (always requires auth)
        tag: staging
      - url: https://localhost:5001/
        description: local dev/test server with tls
        tag: localhost-https
      - url: http://localhost:5000/
        description: local dev/test server
        tag: localhost

[tlmii]

@bradygaster I'm not sure how we can support this - that YAML snippet from @embix is just a piece of his OpenAPI description (the servers field of the main OpenAPI object) so we can't really modify what we expect there. Unless I'm missing something from what you're describing.

As a side note, I think its odd that the spec doesn't support explicitly named environments or anything like that. But as far as I can tell, it doesn't.

[bradygaster]

Ah, good to know, not seeing that YAML in the context of the full spec got me a little off-track. Good point. Don't know about the naming-of-servers, but I feel confident @darrelmiller would know if that's either already been discussed/requested and if so, why we don't have it. :)

Maybe we just craft ourselves some HttpRepl-specific OpenAPI extensions and watch him squirm a little? :)

[embix]

that YAML snippet from @embix is just a piece of his OpenAPI description (the servers field of the main OpenAPI object) so we can't really modify what we expect there.

Exactly.

Even if we explicitly tamper with the auto generation to insert environments/tags that seems like a violation of the OpenAPI standard as of 3.0.3. It may be worth to suggest a discussion about an inclusion of such a tag to OpenAPI, but that is another matter (and an RFC-like spec design process).

We could however use something like servers x-environment (see:Specification Extensions) and suggest an inclusion as optional tag in the OpenAPI standard to spread the word once it's included in HttpRepl (as a beta feature - it's name may change during the spec review/design process). That would make it easier to get it included in tooling like SwashBuckle or fizz (or go-swagger😅).

OT: if links are not pointing to the correct section it's because they use some js magic fiddling with html anchors unfortunately.