Skip to content

Latest commit

 

History

History
173 lines (116 loc) · 5.25 KB

README.md

File metadata and controls

173 lines (116 loc) · 5.25 KB
Raw

GrapeSwaggerRails

Gem Version Build Status Dependency Status Code Climate

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

Compatibility

GrapeSwaggerRails is compatible with the following versions of grape and grape-swagger.

grape grape-swagger
0.9.0 0.8.0
0.10.0 0.9.0

Usage

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

mount GrapeSwaggerRails::Engine => '/swagger'

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

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

You can dynamically set app_url for each request use a before_filter_proc:

GrapeSwaggerRails.options.before_filter_proc = proc {
  GrapeSwaggerRails.options.app_url = request.protocol + request.host_with_port
}

You can set the app name, default is "Swagger".

GrapeSwaggerRails.options.app_name = 'Swagger'

You can hide the header form (shown by default).

GrapeSwaggerRails.options.hide_api_selector = true

You can specify additional headers to add to each request:

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

You can set docExpansion with "none" or "list" or "full", default is "none". See the official Swagger-UI documentation about SwaggerUi Parameters.

GrapeSwaggerRails.options.doc_expansion = 'list'

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' # Or 'bearer' for OAuth
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 before option to inspect the request before Swagger UI:

GrapeSwaggerRails.options.before_filter do |request|
  # 1. Inspect the `request` or access the Swagger UI controller via `self`.
  # 2. Check `current_user` or `can? :access, :api`, etc.
  # 3. Redirect or error in case of failure.
end

Updating Swagger UI from Dist

To update Swagger UI from its distribution, run bundle exec rake swagger_ui:dist:update. Examine the changes carefully.

NOTE: This action should be run part of this gem (not your application). In case if you want to make it up-to-date, clone the repo, run the rake task, examine the diff, fix any bugs, make sure tests pass and then send PR here.

Enabling in a Rails-API Project

The grape-swagger-rails gem uses the Rails asset pipeline for its Javascript and CSS. Enable the asset pipeline with rails-api.

Add sprockets to config/application.rb.

require 'sprockets/railtie'

Include JavaScript in app/assets/javascripts/application.js.

//
//= require_tree .

Include CSS stylesheets in app/assets/stylesheets/application.css.

/*
*= require_tree .
*/

Contributors

Contributing

See CONTRIBUTING.

License

MIT License, see LICENSE.