Can any one tell me how Swagger blocks will generate api-docs.json ??
Opened this issue · 3 comments
I implemented all steps as shown in gem description to implement it. but how it will bind with swagger ui. ? where should i put swagger ui index file and other files in public folder ?
I get this error
Can't read swagger JSON from http://localhost:3000/api-docs.json ??
@vishaltps did you configure rack-cors? Can you open link with your swagger docs in browser and see browser console?
What I did was create a route that points to the apidocs controller and method that has the "render json: Swagger::Blocks.build_root_json(SWAGGERED_CLASSES)" line and that will output the api-docs.json that you're looking for. In the official docs when you add the resources line to your routes.rb you should be able to get the json by hitting the /apidocs endpoint.
There's a couple ways of implementing the Swagger-UI piece. One way is to install the NodeJS swagger component on your box and start up the UI according to those instructions. The one caveat to this method, as referenced by @biow0lf, is that the NodeJS server running the UI is a different server than your Rails app server that's generating the swagger file so your Rails server needs to be setup to serve files (or minimally, that file) with CORS support. There are different ways to set that up based on your Rails version, but there are a lot of tutorials on it that you can find with a quick Google search.
Another method is to have the UI served up by your Rails app itself which eliminates the CORS issue, but has other complexities. The way I set that up was to use the swagger-ui_rails2 gem from 3scale in my Gemfile like so (but this isn't really a maintainable way to do this long-term):
gem 'swagger-ui_rails2', github: '3scale/swagger-ui_rails', branch: 'dev-2.1.3'
and then adding a route to a specific view in my api_docs controller, I used index so it looks like this for me:
match "/docs" => 'docs#index', :via => :get
but if you are using the resources as referenced in the howto you might want a "ui" endpoint, so something like this:
resources :apidocs, only: [:index, :ui]
and adjust your controller action for the ui endpoint because your index endpoint is serving up your apidocs.json. After that I created a view for my api_docs controller endpoint, index.html.haml (I'm using haml instead of erb) but yours might be ui.html.haml, with this code:
.swagger-section
= render 'swagger_ui/swagger_ui', discovery_url: '/apidocs'
And then restart your rails server and you should be able to get to your ui by going to /apidocs/ui
Hope that helps. It's kind of a rough outline blending how I did it and some variation from the official docs, not necessarily the best or recommended way to do it. I can clarify if it's confusing.