Question

I am re-writing (yeah I know!) a Rails app which is largely API driven, using Grape by Intridea and grape-swagger gem to enable Swagger UI for documentation.

So I have a simple hello world app running. Seems discoverable from the swagger test, though it’s giving JSON parse errors at the moment (I’ll look into that next). I want to put the swagger UI into the Rails app, pointed at the /swagger_doc.json so as I build I can make sure the documentation is building properly right along side.

Where do I put the Swagger UI in the rails app? Public directory?

Answer 1

Okay so I found a couple of snafus that were causing nothing to show when I tried just putting it all in the public directory previously.

myapp/public/swagger-ui-1.1.1/files

1) I don’t know if this SHOULD make a difference but the order in which I loaded the rails app and the grape app in the config.ru seemed to make a difference how the routing was handled …I need to understand more how that works. But now the mounted grape app inside routes does what I’d expect. As a result with the swagger-ui unzipped into public then just going to

http://appurl/swagger-ui-1.1.1/ 

gives me the swagger UI. I’ll add more detail to this if there’s an more to it.

EDIT: As there will be other users out there like me who need a helping hand here, I’ll outline it below. It’s pretty easy:

Create /swagger subdirectories in the asset pipeline – I did it under vendor. Copy the lib files over from the swagger UI to these subdirectories. Create a basic docs_controller with an index action (can be empty). Create a views/docs directory and copy the swagger-ui index.html to it. Change the stylesheet and javascript calls to asset-tags in index.html. Add resource route for docs. Change the discoveryURL in the javascript function calling window.swaggerUI to “http://my.root.url/swagger_doc.json” (ideally from ENV variable).

That’s it. It now just works. One gotcha I ran into, using my Grape API under an api subdomain was CORS when Swagger was running on docs subdomain. Easily fixed in Grape by adding something like:

before do
  header "Access-Control-Allow-Origin", "http://#{ENV["BASE_URL"]}"
  header "Access-Control-Allow-Methods", "POST, GET, OPTIONS, PUT"
  header "Access-Control-Max-Age", "1728000"
end

to your Grape api.rb. Hope that all helps someone.