Repository files navigation

Swagger UI as Rails Engine for grape-swagger gem.

• Installation
• Compatibility
• Usage
  • Basic Authentication
  • Pre-fill Authentication
  • API Token Authentication
  • Swagger UI Authorization
    • Integration with DoorKeeper
  • Hiding the API or Authorization text boxes
  • Updating Swagger UI from Dist
  • Enabling in a Rails-API Project
  • Enabling in Rails 6 (Sprokets 5)
• Contributors
• Contributing
• License

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

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

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

mountGrapeSwaggerRails::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 setapp_url for each request use abefore_action:

GrapeSwaggerRails.options.before_actiondoGrapeSwaggerRails.options.app_url=request.protocol +request.host_with_portend

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

GrapeSwaggerRails.options.app_name='Swagger'

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 aboutSwaggerUi Parameters.

GrapeSwaggerRails.options.doc_expansion='list'

You can set supportedSubmitMethods with an array of the supported HTTP methods, default is%w{ get post put delete patch }.

See the official Swagger-UI documentation aboutSwaggerUi Parameters.

GrapeSwaggerRails.options.supported_submit_methods=["get"]

You can set validatorUrl to your own locally deployed Swagger validator, or disable validation by setting this option to nil.This is useful to avoid error messages when running Swagger-UI on a server which is not accessible from outside your network.

GrapeSwaggerRails.options.validator_url=nil

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

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 OAuthGrapeSwaggerRails.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 aboutCustom Header Parameters

If you will know the Authentication key prior to page load or you wish to set it for debug purposes, you can setup so that theapi_key field is pre-filled on page load:

GrapeSwaggerRails.options.api_key_default_value='your_default_value'

To set it based on thecurrent_user or other request-based parameters, try using it inside of yourbefore_action (See Swagger UI Authorization)

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'

If your application used token authentication passed as a header, like Rails does (authenticate_or_request_with_http_token), you can configure Swagger to send the token in this form:

Authorization: Token token="WCZZYjnOQFUYfJIN2ShH1iD24UHo58A6TI"

by specify:

GrapeSwaggerRails.options.api_auth='token'GrapeSwaggerRails.options.api_key_name='Authorization'GrapeSwaggerRails.options.api_key_type='header'GrapeSwaggerRails.options.api_key_placeholder='authorization_token'

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

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

GrapeSwaggerRails.options.before_actiondo |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

Add the following code to the initializer (swagger.rb):

GrapeSwaggerRails.options.before_actiondo |request|GrapeSwaggerRails.options.api_key_default_value=current_user.token.tokenend

In your User model (user.rb) add:

has_one:token,->{order'created_at DESC'},class_name:Doorkeeper::AccessToken,foreign_key::resource_owner_id

If you know in advance that you would like to prevent changing the Swagger API URL, you can hide it using the following:

GrapeSwaggerRails.options.hide_url_input=true

Similarly, you can hide the Authentication input box by adding this:

GrapeSwaggerRails.options.hide_api_key_input=true

By default, these options are false.

To update Swagger UI from itsdistribution, runbundle 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 tomake it up-to-date, clone the repo, run the rake task, examine the diff, fix any bugs, make suretests pass and then send PR here.

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

Add sprockets toconfig/application.rb.

require'sprockets/railtie'

Include JavaScript inapp/assets/javascripts/application.js.

////= require_tree .

Include CSS stylesheets inapp/assets/stylesheets/application.css.

/**= require_tree .*/

Rails 6 top-level targets are determined via./app/assets/config/manifest.js. Specifygrape-swagger-rails asset files as follows.

//= link grape_swagger_rails/application.css//= link grape_swagger_rails/application.js

SeeUpgrading Sprokets for more information.

• unloved
• dapi
• joelvh
• dblock
• ... andmore ...

SeeCONTRIBUTING.

MIT License, seeLICENSE.