0.8.1 not allowing relative paths

[monitorjbl]

There doesn't appear to be a way to specify a relative basePath in 0.8.1. You can use the DemoPathProvider in the example project to set a custom basePath, but the ApiListingReferenceScanner class will try to make it into a URL. Because it uses the UriComponentsBuilder, it cannot handle relative paths.

Relative paths worked in 0.6.5 if you fixed a problem in the swagger.js file, and I don't see any reason in the code for it not to be possible in 0.8.1. They're important for those that use different port numbers and hosts when their app is deployed. Absolute paths are pretty useless in this context.

[monitorjbl]

For reference, the problem is at line 85 of ApiListingReferenceScanner. If this didn't try to make an absolute URI, this would (probably) work.

[adrianbk]

@monitorjbl it's great that you are trying out the library and we appreciate any feedback. There are several reasons why we didn't go with relative paths.

1. The path to the api documentation may not be relative to the path of the actual api endpoints. E.g myapp/documentation/api-docs.. and myapp/api/v1..this is a pretty common occurrence when the app has both secured and unsecured path segements.
2. Consider an application in production sitting behind a proxy like mashery (or multiple proxies and load balancers) you might want to mask relative portions of of your paths so that the external world cannot see the /myapp/api portion of the url. There is no sure way to accomplish this without using some environment specific configuration within your app.
3. Most springmvc applications will have environment specific configurations regardless of swagger so it was felt it wouldn't be a huge burden on developers to configure an absolute base path for swagger. The URI to your API is not going to be an unknown.
4. Tools like swagger-codegen work better with absolute urls.
5. The swagger 1.2 spec recommends the use of absolute paths on resource listings
   "
   The absolute path allows Resource Listings to easily point to multiple servers, so a Resource Listing can be an "uber directory" of apis. Next, the basePath at the resource listing was serving a different purpose than at the Api Declaration, causing much confusion. Finally, the basePath for Resource Listing was an additional configuration to mess up.
   "
6. We wanted a solution that would work seamlessly with swagger-ui. i.e. without having to make any fixes to swagger-ui each time they upgraded the distribution.

Some of the motivation for the absolute URL's was driven by the needs of an application currently running in a production environment with a combination of some of these URL and proxy type complications - it was felt more important to support this.

[monitorjbl]

Makes sense. If you want to be able to support swagger's JS out of the box, explicitly supporting relative paths is a non-starter. For our purposes though, the relative paths work and seem to simplify deployment (nothing to misconfigure). That could change down the line, but for now it's doing the job nicely.

It would still be nice to be able to sneak it in the way we're able to in 0.6.6 though. If you're comfortable enough with Javascript, the changes that need to be made are pretty minimal. The only thing that appears to be preventing it is that explicit URI construction in ApiListingReferenceScanner. It's creating a String anyway, so it's likely that there wouldn't be many side effects if that were to be changed.

[dmoses48]

I have a similar issue. We have multiple domains hitting a single webservice cluster. A client may go to http://foo.com/ or http://bar.com to access our servers. If I hard code the base URL to one or the other than the swagger UI will blow up with a same origin issue. I can fork this project to allow for relative base paths or runtime dynamic base paths. Or I can change the swagger UI to ignore the base paths and always use the same domain it's on.

I would think that dynamic base paths would be better. Only store the SwaggerPathProvider instead of the results from getAppBasePath(). You can then always call getAppBasePath when you need the path. That would allow for a more dynamic implementation of SwaggerPathProvider

[adrianbk]

I have made some slight changes to allow relative urls.
0.8.2.SNAPSHOT
Let me know if it works.
Please see the demo app: http://127.0.0.1:8097/swagger-springmvc-demo/swaggerRelative

Not recommending to use relative URL's the author of swagger-ui states:
"This works, but note that most of the swagger tools will NOT work with relative base paths"

see: see swagger-api/swagger-js#59 for

[monitorjbl]

Awesome! I'll give it a shot tomorrow. Thanks for trying to accommodate us :)