shinnc / grape-swagger-rails

Integration swagger to grape in rails

GrapeSwaggerRails

Swagger UI as Rails Engine for grape-swagger gem

Installation

Add this line to your application's Gemfile:

gem 'grape-swagger-rails'

And then execute:

$ bundle

Or install it yourself as:

$ gem install grape-swagger-rails

Usage

Add this line to ./config/routes.rb:

mount GrapeSwaggerRails::Engine => '/swagger'

Create an initializer (e.g. ./config/initializer/swagger.rb) and specify the URL to your Swagger API schema:

GrapeSwaggerRails.options.url      = '/swagger_doc.json'
GrapeSwaggerRails.options.app_name = 'Swagger'
GrapeSwaggerRails.options.app_url  = 'http://swagger.wordnik.com'

You can specify additional headers to add to each request:

GrapeSwaggerRails.options.headers['Special-Header'] = 'Some Secret Value'

Using the headers option above, you could hard-code Basic Authentication credentials. Alternatively, you can configure Basic Authentication through the UI, as described below.

Basic Authentication

If your application uses Basic Authentication, you can setup Swagger to send the username and password to the server with each request to your API:

GrapeSwaggerRails.options.api_auth     = 'basic'
GrapeSwaggerRails.options.api_key_name = 'Authorization'
GrapeSwaggerRails.options.api_key_type = 'header'

Now you can specify the username and password to your API in the Swagger "API key" field by concatenating the values like this:

username:password

The javascript that loads on the Swagger page automatically encodes the username and password and adds the authorization header to your API request. See the official Swagger documentation about Custom Header Parameters

API Token Authentication

If your application uses token authentication passed as a query param, you can setup Swagger to send the API token along with each request to your API:

GrapeSwaggerRails.options.api_key_name = 'api_token'
GrapeSwaggerRails.options.api_key_type = 'query'

You can use the api_key input box to fill in your API token.

Swagger UI Authorization

You may want to authenticate users before displaying the Swagger UI, particularly when the API is protected by Basic Authentication. Use the authenticate_with option to inspect the request to the Swagger UI:

GrapeSwaggerRails.options.authenticate_with do |request|
  # 1. Inspect the `request` or access the Swagger UI controller via `self`
  # 2. Check `current_user` or `can? :access, :api`, etc....
  # 3. return a boolean value
end

The block above is stored in the authentication_proc option:

GrapeSwaggerRails.options.authentication_proc: Proc.new{|request| # return a boolean value}

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request