Help with Swagger UI and port number

[Simon Roberts]

Hi all,

First, I don't believe I understand the organization of Swagger's docs, so if "RTFM" is an appropriate answer, please feel free to guide me to where that "M" is :)

I have an app that's using Swagger UI for documentation. I had it working with a fairly recent version of the UI (but I don't know what version as I don't know where to find this information, the download page doesn't seem to tell me that. Again, I fear that I'm failing to understand something). Anyway, it was working tolerably, but in an attempt to fix some things related to sub-resources, I upgraded to whatever version of the UI I downloaded yesterday and the 1.3.0RC3 release of Swagger for my JAX-RS service.

I took the UI "index.html" file, and changed the base uri so that it would connect to my service instead of the petstore (Is this really the right file to be working with? It's the only one I found that seemed to be a contender for this role) and it connects to my api-docs URI and shows the entry point listings more or less (still some sub-resources issues). Unfortunately, when I try to invoke an operation, even a simple one, it fails. What I notice in Chrome's javascript console is that it appears to be connecting to the wrong port. That is, the URI to which I connected it for the api-docs is http://localhost:8080/blah... but when it attempts to invoke an operation, it connects to http://localhost/blah... without the 8080. More strange, it gets a result that is "no content", and I can't tell if the UI means "that didn't work" (there should be nothing listening on port 80) or if it actually got a response of some kind, but that response was empty. A third possibility, I suppose, is that it's failing for other unrelated reasons, and the JS console in Chrome is mis-reporting the URI, but that seems unlikely. BTW, I use other tools to connect to my service, and those are successful, so I know for sure that my service is working properly.

Any guidance?

Thanks!

Simon

[Simon Roberts]

BTW, I switched my server to run on port 80 (which is not an option for a long-term fix) and the UI works so I'm now pretty sure that somehow the UI is succeeding in loading the api-docs json data from port 8080 as I need it to, but then does not propagate that port number into the URI from which it tries to load the service.

Hopefully this is easy, can anyone point me at that trivial piece of documentation that I'm missing?

TIA!

[tony tam]

Hi Simon, there are two things:

1) when initializing the UI, you *do* need to put in a URL to the swagger-documentation.  If it's not on port 80, you can specify it in the URL as such:

https://github.com/wordnik/swagger-ui/blob/master/dist/index.html#L22

    $(function () {
      window.swaggerUi = new SwaggerUi({
      url: "http://your-server.com:8000/api/api-docs",

If the swagger-ui properly loads then this configuration is working.

2) the "try it out" feature uses the "basePath" from each specific API Declaration.  For example:

http://petstore.swagger.wordnik.com/api/api-docs/pet

has a base path here:

{

• apiVersion: "1.0.0",
• swaggerVersion: "1.2",
• basePath: "http://petstore.swagger.wordnik.com/api",

This is the location of your *actual* API server--what responds to the requests.  If you're on a non-standard port, put it here and the "try it out" feature should work.

Tony

[Simon Roberts]

Ah, this looks like a step in a good direction. Many thanks Tony,

However, there's still something I don't know how to do: The only way I know of to specify that basePath value is through the servlet init-param in my web.xml. Previously, I allowed this to be a relative URL, and it worked just fine. Now, to make this work, I seem to have to provide an absolute URL. That won't work for me, because I need my UI to be loaded from a server, and to access the docs and service based on a path relative to the place it was loaded from. This is because my service will run in a variety of locations, and also be deployed on virtual IPs, for any of which the base url cannot be known at build time. I had fixed this by dynamically computing the "url" value in the UI code: like this:

   var base = document.URL.replace("/index.html", "/");  // <============= Calculate

    $(function () {

      window.swaggerUi = new SwaggerUi({

      //url: "http://petstore.swagger.wordnik.com/api/api-docs",   // <============= Not this,

      url: base + "v1/api-docs",  // <============= But this...

So, the final part of the question is, how can I insert a dynamically computed  basePath into "the system" in the same way as I'm calculating the url part?

Many thanks!

Simon

[Pablo Alvarez Danker]

I was experimenting a similar problem: The "Try-out" button would send all requests to port 80.

I modified Object.defineProperties in shred.bundle.js so it reads the port from URI of the current document. 

It works for me.

 

  port: {

    get: function() {

      if (!this._port) {

  // use the port of the URI if available

var port = document.URL.match(/:(\d+)\//);

if (port) {

return this._port = port[2];

}

        

switch(this.scheme) {

          case "https": return this._port = 443;

          case "http":

          default: return this._port = 80;

        }

[Philip Liou]

Hey Tony, 

I tried to specify the port number in the basePath for a resource, but when I add a port number (change from "basePath": "dev.best-local.com" to "basePath": "dev.best-local.com:2378") it doesn't work. Specifically, the UI doesn't load properly because of a parsing error in the Javascript, and you can't expand the resources anymore.

Is there an easy way to specify the port number so that I can have the Try It Now feature work with a custom port? 

thanks,

philip

[tony tam]

Hi, sorry for the delay.  You should be able to use override the port in the basePath.  What version of the swagger spec are you using?