fliptoo/swagger-express — pull request #6 by slajax (2014-01-29 18:18:02+00:00)
Title: basePath should still be able to be set so it can be passed to swagger.js in the response

@calmdev's changes to parameterize swagger were awesome. I was super happy to see that. Great work. We just upgraded and found that cf31676f7b33404d97d44ae1b1823b38bcae27d8 is problematic (at least for us).

The problem is that basePath is used for more then just setting the host in the UI. I agree that swagger-express doesn't need to modify the UI when the app starts. We found it was buggy and we saw a lot of issues where it would leave index.html blank quite often.

That said however, basePath is still use for other important things so I don't think it should be removed completely.

It's primary purpose is to be passed back as part of the schema.json definition to help wordnik/swagger-js to decide how to orient itself to the API routing. When a basePath isn't defined, swagger does some guess work as you can see here: https://github.com/wordnik/swagger-js/blob/master/src/swagger.coffee#L84-L91 - and unfortunately it doesn't appear to always get the assumption right as was the case for us. This causes the UI to not assimilate with the schema and everything breaks.

I feel a good compromise is to just return the ability to set the basePath when needed so you can proxy this setting to swagger.js. If you don't it will be omitted and you still get the fall back url parsing that is built into swagger.js

Lemme know if you have any questions.