Rewritten test example, updated README.

CHANGELOG.md

@@ -9,6 +9,7 @@
 * Rewritten .gemspec and removed Jeweler - [@dblock](https://github.com/dblock).
 * Added `GrapeEntity::VERSION` - [@dblock](https://github.com/dblock).
 * Added Rubocop, Ruby-style linter - [@dblock](https://github.com/dblock).
+* [#126](https://github.com/tim-vandecasteele/grape-swagger/pull/126): Rewritten demo in the `test` folder with CORS enabled - [@dblock](https://github.com/dblock).
 * Your Contribution Here
 
 ### 0.7.2 (February 6, 2014)

Gemfile.lock

@@ -55,6 +55,7 @@ GEM
     rack (1.5.2)
     rack-accept (0.4.5)
       rack (>= 0.4)
+    rack-cors (0.2.9)
     rack-mount (0.8.3)
       rack (>= 1.0.0)
     rack-test (0.6.2)
@@ -104,6 +105,7 @@ PLATFORMS
 DEPENDENCIES
   bundler
   grape-swagger!
+  rack-cors
   rack-test
   rake
   rdoc

README.md

@@ -3,9 +3,12 @@
 [![Build Status](https://travis-ci.org/tim-vandecasteele/grape-swagger.svg?branch=master)](https://travis-ci.org/tim-vandecasteele/grape-swagger)
 
 ## What is grape-swagger?
-grape-swagger provides an autogenerated documentation for your [grape](https://github.com/intridea/grape)-API. The generated documentation is Swagger-compliant, meaning it can easily be discovered in [Swagger UI](https://github.com/wordnik/swagger-ui)
 
-## Related projects
+The grape-swagger gem provides an autogenerated documentation for your [Grape](https://github.com/intridea/grape) API. The generated documentation is Swagger-compliant, meaning it can easily be discovered in [Swagger UI](https://github.com/wordnik/swagger-ui). You should be able to point [the petstore demo](http://petstore.swagger.wordnik.com) to your API.
+
+![Demo Screenshot](test/splines.png)
+
+## Related Projects
 
 * [Grape](https://github.com/intridea/grape)
 * [Swagger UI](https://github.com/wordnik/swagger-ui)
@@ -18,7 +21,7 @@ Add to your Gemfile:
 
 ## Usage
 
-Once you have the gem installed, mount all your different APIs (with ```Grape::API``` superclass) on a root node. In the root class definition, also include ```add_swagger_documentation```, this sets up the system and registers the documentation on '/swagger_doc.json'. Setup done, you can restart your local server now.
+Mount all your different APIs (with ```Grape::API``` superclass) on a root node. In the root class definition, include ```add_swagger_documentation```, this sets up the system and registers the documentation on '/swagger_doc.json'. See [test/api.rb](test/api.rb) for a simple demo.
 
 
 ``` ruby
@@ -35,39 +38,96 @@ end
 ```
 
 To explore your API, either download [Swagger UI](https://github.com/wordnik/swagger-ui) and set it up yourself or go to the [online swagger demo](http://petstore.swagger.wordnik.com/) and enter your localhost url documentation root in the url field (probably something in the line of http://localhost:3000/swagger_doc.json).
-If you use the online demo, make sure your API supports foreign requests by enabling CORS in grape, otherwise you'll see the API description, but requests on the API won't return. You can do this by putting below code in your Grape API definition:
+
+### CORS
+
+If you use the online demo, make sure your API supports foreign requests by enabling CORS in Grape, otherwise you'll see the API description, but requests on the API won't return. Use [rack-cors](https://github.com/cyu/rack-cors) to enable CORS.
 
 ```` ruby
+require 'rack/cors'
+use Rack::Cors do
+  allow do
+    origins '*'
+    resource '*', headers: :any, methods: [ :get, :post, :put, :delete, :options ]
+  end
+end
+```
+
+Alternatively you can set CORS headers in a Grape `before` block.
+
+``` ruby
 before do
-    header['Access-Control-Allow-Origin'] = '*'
-    header['Access-Control-Request-Method'] = '*'
+  header['Access-Control-Allow-Origin'] = '*'
+  header['Access-Control-Request-Method'] = '*'
 end
 ````
 
 ## Configure
 
-You can pass a hash with some configuration possibilities to ```add_swagger_documentation```, all of these are optional:
-
-* ```:target_class``` The API class to document, default `self`.
-* ```:mount_path``` The path where the API documentation is loaded, default '/swagger_doc'.
-* ```:class_name```
-* ```:markdown``` Allow markdown in `notes`, default `false`.
-* ```:hide_format``` , Don't add '.(format)' to the end of URLs, default `false`.
-* ```:api_version``` Version of the API that's being exposed.
-* ```:base_path``` Basepath of the API that's being exposed, this configuration parameter accepts a Proc to evaluate base_path, useful when you need to use request attributes to determine the base_path.
-* ```:authorizations``` Added to the `authorizations` key in the JSON documentation.
-* ```:include_base_url``` Add base path to the URLs, default `true`.
-* ```:root_base_path``` Add `basePath` key to the JSON documentation, default `true`.
-* ```:models``` Allows adds an array with the entities for build models specifications. You need to use grape-entity gem.
-* ```:hide_documentation_path``` Don't show the '/swagger_doc' path in the generated swagger documentation.
-* ```:format```
-* ```:info``` Added to the `info` key in the JSON documentation.  `info` is a hash that may contain:
-  * ```:title:``` The API title to be displayed on the API homepage.
-  * ```:description:``` A description of the API.
-  * ```:contact:``` Contact email.
-  * ```:license:``` The name of the license.
-  * ```:license_url:``` The URL of the license.
-  * ```:terms_of_service_url:``` The URL of the API terms and conditions.
+You can pass a hash with optional configuration settings to ```add_swagger_documentation```.
+
+#### target_class
+
+The API class to document, default `self`.
+
+#### mount_path
+
+The path where the API documentation is loaded, default is `/swagger_doc`.
+
+#### class_name
+
+API class name.
+
+#### markdown
+
+Allow markdown in `notes`, default is `false`. See below for details.
+
+#### hide_format
+
+Don't add `.(format)` to the end of URLs, default is `false`.
+
+#### api_version
+
+Version of the API that's being exposed.
+
+#### base_path
+
+Base path of the API that's being exposed. This configuration parameter accepts a `proc` to evaluate `base_path`, useful when you need to use request attributes to determine its value.
+
+#### authorizations
+
+This value is added to the `authorizations` key in the JSON documentation.
+
+#### include_base_url
+
+Add base path to the URLs, default is `true`.
+
+#### root_base_path
+
+Add `basePath` key to the JSON documentation, default is `true`.
+
+#### models
+
+A list of entities to document. Combine with the [grape-entity](https://github.com/intridea/grape-entity) gem. See below for details.
+
+#### hide_documentation_path
+
+Don't show the `/swagger_doc` path in the generated swagger documentation.
+
+#### format
+
+Documentation response format, default is `:json`.
+
+#### info
+
+A hash merged into the `info` key of the JSON documentation. This may contain:
+
+* `:title`: The API title to be displayed on the API homepage.
+* `:description`: A description of the API.
+* `:contact`: Contact email.
+* `:license`: The name of the license.
+* `:license_url`: The URL of the license.
+* `:terms_of_service_url`: The URL of the API terms and conditions.
 
 ## Swagger Header Parameters
 
@@ -90,63 +150,52 @@ desc "Return super-secret information", {
 
 ## Hiding an Endpoint
 
-You can hide an endpoint by adding ```:hidden => true``` in the description of the endpoint:
+You can hide an endpoint by adding ```hidden: true``` in the description of the endpoint:
 
 ``` ruby
-desc 'Hide this endpoint', {
-  :hidden => true
-}
+desc 'Hide this endpoint', hidden: true
 ```
 
+## Overriding Auto-Generated Nicknames
 
-# Overriding auto generated nickname for an endpoint
-
-You can specify a swagger nickname to use instead of the auto generated name by adding ```:nickname => 'string'``` in the description of the endpoint.
+You can specify a swagger nickname to use instead of the auto generated name by adding `:nickname 'string'``` in the description of the endpoint.
 
 ``` ruby
-desc 'get a full list of Pets', {
-  :nickname => 'getAllPets'
-}
+desc 'Get a full list of pets', nickname: 'getAllPets'
 ```
 
-
 ## Grape Entities
 
 Add the [grape-entity](https://github.com/agileanimal/grape-entity) gem to our Gemfile.
-Please refer to the [grape-entity documentation](https://github.com/intridea/grape-entity/blob/master/README.md)
-for more details.
 
 The following example exposes statuses. And exposes statuses documentation adding :type and :desc.
 
 ```ruby
 module API
-
   module Entities
     class Status < Grape::Entity
-      expose :text, :documentation => { :type => "string", :desc => "Status update text." }
-      expose :links, using: Link, :documentation => { type: 'link', is_array: true }
+      expose :text, documentation: { type: 'string', desc: 'Status update text.' }
+      expose :links, using: Link, documentation: { type: 'link', is_array: true }
     end
-    
+
     class Link < Grape::Entity
-      def self.entity_name 
+      def self.entity_name
         'link'
       end
-    
-      expose :href, :documentation => { :type => 'url' }
-      expose :rel, :documentation => { :type => 'string'}
+
+      expose :href, documentation: { type: 'url' }
+      expose :rel, documentation: { type: 'string'}
     end
   end
 
   class Statuses < Grape::API
     version 'v1'
 
-    desc 'Statuses index', {
-      :entity => API::Entities::Status
-    }
+    desc 'Statuses index', entity: API::Entities::Status
     get '/statuses' do
       statuses = Status.all
       type = current_user.admin? ? :full : :default
-      present statuses, with: API::Entities::Status, :type => type
+      present statuses, with: API::Entities::Status, type: type
     end
   end
 end
@@ -160,26 +209,25 @@ end
 module API
   module Entities
     class Client < Grape::Entity
-      expose :name, :documentation => { :type => "string", :desc => "Name" }
-      expose :addresses, using: Entities::Address, documentation: {type: 'Address', desc: 'Addresses.', param_type: 'body', is_array: true}
+      expose :name, documentation: { type: 'string', desc: 'Name' }
+      expose :addresses, using: Entities::Address,
+        documentation: { type: 'Address', desc: 'Addresses.', param_type: 'body', is_array: true }
     end
 
     class Address < Grape::Entity
-      expose :street, :documentation => { :type => "string", :desc => "Street." }
+      expose :street, documentation: { type: 'string', desc: 'Street.' }
     end
-
   end
 
   class Clients < Grape::API
     version 'v1'
 
-    desc 'Clients index', {
-      params: Entities::Client.documentation
-    }
+    desc 'Clients index', params: Entities::Client.documentation
     get '/clients' do
       ...
     end
   end
+
   add_swagger_documentation models: [Entities::Client, Entities::Address]
 end
 ```
@@ -192,30 +240,30 @@ Note: `is_array` is `false` by default.
 module API
   module Entities
     class Client < Grape::Entity
-      expose :name, :documentation => { :type => "string", :desc => "Name" }
-      expose :address, using: Entities::Address, documentation: {type: 'Address', desc: 'Addresses.', param_type: 'body', is_array: false}
+      expose :name, documentation: { type: 'string', desc: 'Name' }
+      expose :address, using: Entities::Address,
+        documentation: { type: 'Address', desc: 'Addresses.', param_type: 'body', is_array: false }
     end
 
     class Address < Grape::Entity
-      expose :street, :documentation => { :type => "string", :desc => "Street" }
+      expose :street, documentation: { type: 'string', desc: 'Street' }
     end
   end
 
   class Clients < Grape::API
     version 'v1'
 
-    desc 'Clients index', {
-      params: Entities::Client.documentation
-    }
+    desc 'Clients index', params: Entities::Client.documentation
     get '/clients' do
       ...
     end
   end
+
   add_swagger_documentation models: [Entities::Client, Entities::Address]
 end
 ```
 
-## Swagger Additions
+## Markdown in Notes
 
 The grape-swagger gem allows you to add an explanation in markdown in the notes field. Which would result in proper formatted markdown in Swagger UI. The default Swagger UI doesn't allow HTML in the notes field, so you need to use an adapted version of Swagger UI (you can find one at https://github.com/tim-vandecasteele/swagger-ui/tree/vasco).
 
@@ -225,7 +273,7 @@ Be sure to enable markdown in the `add_swagger_documentation` with 'markdown: tr
 
 ``` ruby
 desc "Reserve a virgin in heaven", {
-  :notes => <<-NOTE
+  notes: <<-NOTE
     Virgins in Heaven
     -----------------
 
@@ -244,10 +292,10 @@ desc "Reserve a virgin in heaven", {
 }
 ```
 
-You can also document the HTTP status codes that your API returns with this syntax:
+You can also document the HTTP status codes that your API returns with the following syntax.
 
 ``` ruby
-get '/', :http_codes => [
+get '/', http_codes: [
   [400, "Invalid parameter entry"],
 ] do
   ...

grape-swagger.gemspec

@@ -21,6 +21,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'rspec', '~> 3.0'
   s.add_development_dependency 'bundler'
   s.add_development_dependency 'rack-test'
+  s.add_development_dependency 'rack-cors'
   s.add_development_dependency 'rubocop', '0.24.1'
 
   s.files         = `git ls-files`.split("\n")