Added documentation about new config options

Author: joelvh

README.md

@@ -6,7 +6,9 @@ Swagger UI as Rails Engine for grape-swagger gem
 
 Add this line to your application's Gemfile:
 
-    gem 'grape-swagger-rails'
+```ruby
+gem 'grape-swagger-rails'
+```
 
 And then execute:
 
@@ -16,22 +18,75 @@ Or install it yourself as:
 
     $ gem install grape-swagger-rails
 
-## Usage: add this line to your routes.rb
+## Usage
 
-    mount GrapeSwaggerRails::Engine => '/swagger'
+Add this line to `./config/routes.rb`:
 
-Create `./config/initializer/swagger.rb` with lines:
+```ruby
+mount GrapeSwaggerRails::Engine => '/swagger'
+```
 
-    GrapeSwaggerRails.options.url      = "/swagger_doc.json"
-    GrapeSwaggerRails.options.app_name = 'Swagger'
-    GrapeSwaggerRails.options.app_url  = 'http://swagger.wordnik.com'
+Create an initializer (e.g. `./config/initializer/swagger.rb`) and specify the URL to your Swagger API schema:
+
+```ruby
+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:
+
+```ruby
+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:
+
+```ruby
+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](https://github.com/wordnik/swagger-ui#custom-header-parameters---for-basic-auth-etc)
+
+### 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:
+
+```ruby
+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:
+
+```ruby
+GrapeSwaggerRails.options.authentication_proc: Proc.new{|request| # return a boolean value}
+```
 
 ## Known problems
 
 To avoid problems with the validation parameters in `POST` request using this gem,
 please use the head version:
 
-    gem 'grape-swagger', :git=>'git://github.com/jhecking/grape-swagger.git'
+```ruby
+gem 'grape-swagger', :git=>'git://github.com/jhecking/grape-swagger.git'
+```
 
 ## Contributing