How to use it in Rails?

[volkanunsal]

Can someone help me understand how I can configure grape-swagger on a Rails app? I followed the instructions, but I'm still having trouble. swagger_doc.json is throwing a routing error.

...help??

[tim-vandecasteele]

If you follow the example, you still need to mount API::Root in your routes.rb, i.e.:

MyApplication::Application.routes.draw do

  mount API::Root => '/'

end

[volkanunsal]

Oh cool. So I created an initializer called swagger.rb and put the block in there and add the line above in the routes.rb. Now I see the json page, but the apis array is empty except for the paths to swagger_doc.json. This is what the files look like:

# lib/v1.rb
class V1 < Grape::API
  ...
end

# config/initializers/swagger.rb
require 'grape-swagger'
module API
  class Root < Grape::API
    mount V1
    add_swagger_documentation
  end
end

[tim-vandecasteele]

Does the lib/v1.rb file contain proper API definitions? If the file would be empty or not contain any routes itself, the apis would be empty too.

Is your Grape API itself accessible?

[volkanunsal]

Yup, I can access the grape API just as normal. Here is an example of an endpoint from lib/v1.rb:

  resource :account do 
    desc "Update user's credit card id"
    post "/:id/update_credit_card_id" do 
      authenticate!
      ...
    end
  end

[volkanunsal]

It just occurred to me that this issue might be caused by my use of grape-rabl.

[volkanunsal]

I found the reason for this bug. Apparently, Grape does this weird thing where, if you specify a version, i.e. version 'v1', it completely screws up the combined_routes hash. Example:

Without a version number:

{"accounts"=>
  [version=, method=POST, path=/accounts/:id/update_credit_card_id(.:format)],
 "app"=>[version=, method=GET, path=/app(.:format)],
 "purchases"=>[version=, method=GET, path=/purchases/:id(.:format)],
 "tokens"=>
  [version=, method=GET, path=/tokens(.:format),
   version=, method=DELETE, path=/tokens(.:format)],
 "categories"=>[version=, method=GET, path=/categories(.:format)],
 "events"=>
  [version=, method=GET, path=/events/:id/purchase_preview(.:format),
   version=, method=POST, path=/events/:id/buy(.:format),
   version=, method=GET, path=/events/latest(.:format),
   version=, method=GET, path=/events/near(.:format)]}

With a version number:

{":version"=>
  [version=v1, method=POST, path=/:version/accounts/:id/update_credit_card_id(.:format),
   version=v1, method=GET, path=/:version/app(.:format),
   version=v1, method=GET, path=/:version/purchases/:id(.:format),
   version=v1, method=GET, path=/:version/tokens(.:format),
   version=v1, method=DELETE, path=/:version/tokens(.:format),
   version=v1, method=GET, path=/:version/categories(.:format),
   version=v1, method=GET, path=/:version/events/:id/purchase_preview(.:format),
   version=v1, method=POST, path=/:version/events/:id/buy(.:format),
   version=v1, method=GET, path=/:version/events/latest(.:format),
   version=v1, method=GET, path=/:version/events/near(.:format)]}

Pretty annoying. Should I open a ticket with them?

[tim-vandecasteele]

Nice debugging.

The combined routes is an instance variable generated by grape-swagger, so the bug is in grape-swagger itself.

To define the proper 'parent resource', grape swagger looks at the first element of the path (in this case, :version) and bundles the routes based on that.

A workaround might be to mount all your version v1-APIs on a v1-root-API and add the swagger documentation to each version of your API, although I should try it to know if it would actually work.

Do you have a proposal how you would like the splitup in swagger?

[volkanunsal]

You don't need to do regex matching to get the path here. You can get that and the name of the resource from the @options instance variable in Grape::Route class. That would save you from the versioned API problem, i.e.

        mounts::routes.each do |route|
          resource = route.instance_variable_get("@options")[:namespace] || 'global'
          @combined_routes[resource] ||= []
          @combined_routes[resource] << route
        end

I fixed it using that and adding a nested map loop in the endpoint for swagger_doc.json. This is not ideal though because nickname is coming out looking like this:

nickname: "POST--version-accounts--id-update_credit_card_id---format-",

I'll send you a pull request so you can evaluate it.

[volkanunsal]

Coming back to this after a couple of months break. Another thing I realize it needs to have is automated reloading. Putting swagger.rb in the initializers folder requires me to restart the app in order to see my changes to the API.

[tim-vandecasteele]

The automatic reloading is probably due to an issue with grape itself. Check ruby-grape/grape#131 for a workaround.

[diarmuidoconnor]

Hi,
I have a Rails 3 application with a REST API built using Grape. API works fine when I test it with curl. I’ve followed your instructions for adding grape-swagger and then try to explore it using the online swagger demo – everything renders ok. However, when I test any part of my api using the demo, the response body is empty and the response code is 0; although the log file on the server-side shows the request being handled. Any thoughts as to what is wrong?

Many thanks, Diarmuid

[tim-vandecasteele]

Could you open a new ticket with some sample code?

Hard to say without an actual example.