Merge pull request #10 from wellthie/master

Updated README.md with new options

Author: unloved

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
 

app/views/grape_swagger_rails/application/index.html.erb

@@ -16,15 +16,15 @@
       headers: options.headers,
       supportedSubmitMethods: ['get', 'post', 'put', 'delete'],
       onComplete: function(swaggerApi, swaggerUi){
-        if(console) {
+        if('console' in window) {
           console.log("Loaded SwaggerUI")
           console.log(swaggerApi);
           console.log(swaggerUi);
         }
         $('pre code').each(function(i, e) {hljs.highlightBlock(e)});
       },
       onFailure: function(data) {
-        if(console) {
+        if('console' in window) {
           console.log("Unable to Load SwaggerUI");
           console.log(data);
         }
@@ -34,12 +34,11 @@
 
     $('#input_apiKey').change(function() {
       var key = $('#input_apiKey')[0].value;
-      console.log("key: " + key);
+      
       if(key && key.trim() != "") {
         if (options.api_auth == 'basic') {
           key = "Basic " + Base64.encode(key);
         }
-        console.log("added key " + key);
         window.authorizations.add("key", new ApiKeyAuthorization(options.api_key_name, key, options.api_key_type));
       } else {
         window.authorizations.add("key", null);

lib/grape-swagger-rails.rb

@@ -10,13 +10,17 @@ def authenticate_with(&block)
   mattr_accessor :options
 
   self.options = Options.new(
+    
     url:                  '/swagger_doc.json',
-    api_key_name:         'api_key',
-    api_key_type:         'query',
-    api_auth:             '', # 'basic'
-    headers:              {},
     app_name:             'Swagger',
     app_url:              'http://swagger.wordnik.com',
+    
+    headers:              {},
+    
+    api_auth:             '',        # 'basic'
+    api_key_name:         'api_key', # 'Authorization'
+    api_key_type:         'query',   # 'header'
+    
     authentication_proc:  nil # Proc used as a controller before filter that returns a boolean
   )