Ability to have multiple hosts (per environment) in one swagger spec

[cabbonizio]

We are currently using Swagger for documenting our API's but have disabled the test harness feature (supportedSubmitMethods = null) for now. We intend on enabling the test harness, but would like to be able to specify different hosts. All of our APIs are managed through an API Gateway product and all of our clients are able to use a single host per environment. The URI is exactly the same (of course) so just the host changes. For instance:

dev.example.com (development/sandbox)
int.example.com (integration)
qa.example.com (quality/uat)
example.com (production)

What would helpful is if within a single Swagger spec, we can specify the environment name via dropdown (at top or bottom of page?) and behind that is the hostname. This would allow us to have a single place for clients to read documentation, and test services in any environment which they please.

Apologies if this is an open issue or asked for before, but I think this would be very useful from a test harness perspective. What do you think?

[webron]

This question has a few aspects to it. The first is the ability to provide a templated host, which is not supported by the spec right now, but there's a feature request for it - OAI/OpenAPI-Specification#169.

The second is actually doing that in the ui. Now, in a way, you /can/ do it in the UI right now, but it would require some javascript work on your behalf. Adding the drop down is easy, if you make the list static and don't expect it to come from the spec. You can manipulate the swagger-client by setting the host based on the user choice (this is a relatively recent addition).

If you still prefer to get the list from the swagger spec itself, you can always use vendor extensions to specify the list and process that to generate the hosts drop down.

[cabbonizio]

Hi @webron thanks for your response. I would prefer to get the list from the Swagger spec itself so it seems simple enough to create a vendor extension for the host list, but I am a little fuzzy with my javascript skills on this one to render the dropdown. I have definitely generated a dropdown via javascript in the past, but just trying to figure out where to do this. Can you recommend where to start? Is that code in the swagger-ui.js or swagger-ui-min.js?

I was even considering putting a drop down next to each "Try it out!" button so the user doesn't have to scroll to the top or bottom for each operation they want to test.

It's good to know there's a feature request in the OpenAPI spec github site. Sounds like it will very useful down the line.

[webron]

I'd suggest 'voting' on the issue. When the time comes, it'll help us see which issues are more popular.

As for the actual implementation, doubt my JS skills are better than yours ;) Hopefully @ponelat or @fehguy could provide more guidance there.

[cabbonizio]

@webron I appreciate you extending this for voting! LOL about the JS skills ;-P

Would like to hear @fehguy and @ponelat opinion.

[jcunningham77]

+1

[rglowzenski]

+1 This feature would be useful to us as well.

[webron]

Maybe I wasn't clear... +1'ing this issue is not going to help ;) It's the linked issue in the spec :)

[cabbonizio]

Ok will go and +1 the linked issue, thanks for the clearing this up!

[cabbonizio]

@webron, curious is the OpenAPI github project going to be where we track issues and enhancements going forward for Swagger? Should I be opening any new issues on the swagger-ui github site?

[webron]

The Swagger Specification was donated to the Linux Foundation under the Open API Initiative as an open governance model and has been renamed to the OpenAPI Specification.

The Swagger name lives on as the toolset around the spec. So if you feature requests for the spec, open those there. If you have issues with the tools, open them here.

[cabbonizio]

Roger that

[guy16510]

I ended up creating 2 swagger config files with different host names, then reloading the swagger object applying the different swagger file pathway.

[navel-levanek]

+1 This feature would be useful to us as well.

[palkapawel]

+1 This feature would be useful to us as well.

[webron]

This has been covered by OAI/OpenAPI-Specification#646.

[jd-carroll]

Now that this has been added to the 3.0 spec, what needs to be done from a UI standpoint to enable this feature? This will be a valuable addition to the spec so I'm anxious to help get it running!

[webron]

You'd have to wait for us to work on 3.0 support, which won't happen before the spec stabilizes.