Merge branch 'pr/54'

Author: Tim Vandecasteele

Gemfile

@@ -4,6 +4,7 @@ source "http://rubygems.org"
 #   gem "activesupport", ">= 2.3.5"
 
 gem 'grape', '>= 0.2.0'
+gem 'grape-entity', '~> 0.3.0'
 gem 'kramdown'
 
 # Add dependencies to develop your gem here.

Gemfile.lock

@@ -20,6 +20,9 @@ GEM
       rack-accept
       rack-mount
       virtus
+    grape-entity (0.3.0)
+      activesupport
+      multi_json (>= 1.3.2)
     hashie (2.0.5)
     i18n (0.6.1)
     jeweler (1.8.4)
@@ -71,6 +74,7 @@ PLATFORMS
 DEPENDENCIES
   bundler (> 1.0.0)
   grape (>= 0.2.0)
+  grape-entity (~> 0.3.0)
   jeweler (~> 1.8.4)
   kramdown
   pry

README.markdown

@@ -33,7 +33,7 @@ module API
 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). 
+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:
 
 ```` ruby
@@ -53,23 +53,54 @@ You can pass a hash with some configuration possibilities to ```add_swagger_docu
 
 ## Swagger Header Parameters
 
-Swagger also supports the documentation of parameters passed in the header. Since grape's ```params[]``` doesn't return header parameters we can 
+Swagger also supports the documentation of parameters passed in the header. Since grape's ```params[]``` doesn't return header parameters we can
 to specify header parameters seperately in a block after the description.
 
 ``` ruby
 desc "Return super-secret information", {
   headers: {
     "XAuthToken" => {
       description: "Valdates your identity",
-      required: true 
+      required: true
     },
     "XOptionalHeader" => {
       description: "Not reallly needed",
-      required: false 
+      required: false
     }
   }
 }
 ```
+### 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/gileanimal/grape-entity/blob/master/README.markdown)
+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." }
+    end
+  end
+
+  class Statuses < Grape::API
+    version 'v1'
+
+    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
+    end
+  end
+end
+```
 
 ## Swagger additions
 grape-swagger 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).

grape-swagger.gemspec

@@ -48,6 +48,7 @@ Gem::Specification.new do |s|
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<grape>, [">= 0.2.0"])
+      s.add_runtime_dependency(%q<grape-entity>, ["~> 0.3.0"])
       s.add_runtime_dependency(%q<kramdown>, [">= 0"])
       s.add_development_dependency(%q<shoulda>, [">= 0"])
       s.add_development_dependency(%q<rdoc>, ["~> 3.12"])

lib/grape-swagger.rb

@@ -41,7 +41,8 @@ def self.setup(options)
               :api_version => '0.1',
               :markdown => false,
               :hide_documentation_path => false,
-              :hide_format => false
+              :hide_format => false,
+              :models => []
             }
             options = defaults.merge(options)
 
@@ -84,10 +85,12 @@ def self.setup(options)
             get "#{@@mount_path}/:name" do
               header['Access-Control-Allow-Origin'] = '*'
               header['Access-Control-Request-Method'] = '*'
+              models = []
               routes = @@target_class::combined_routes[params[:name]]
               routes_array = routes.map do |route|
                 notes = route.route_notes && @@markdown ? Kramdown::Document.new(strip_heredoc(route.route_notes)).to_html : route.route_notes
                 http_codes = parse_http_codes route.route_http_codes
+                models << route.route_entity if route.route_entity
                 operations = {
                     :notes => notes,
                     :summary => route.route_description || '',
@@ -96,20 +99,23 @@ def self.setup(options)
                     :parameters => parse_header_params(route.route_headers) +
                       parse_params(route.route_params, route.route_path, route.route_method)
                 }
+                operations.merge!({:responseClass => route.route_entity.to_s.split('::')[-1]}) if route.route_entity
                 operations.merge!({:errorResponses => http_codes}) unless http_codes.empty?
                 {
                   :path => parse_path(route.route_path, api_version),
                   :operations => [operations]
                 }
               end
 
-              {
+              api_description = {
                 apiVersion: api_version,
                 swaggerVersion: "1.1",
                 basePath: parse_base_path(base_path, request),
                 resourcePath: "",
                 apis: routes_array
               }
+              api_description[:models] = parse_entity_models(models) unless models.empty?
+              api_description
             end
           end
 
@@ -172,6 +178,19 @@ def parse_path(path, version)
               version ? parsed_path.gsub('{version}', version) : parsed_path
             end
 
+            def parse_entity_models(models)
+              result = {}
+              models.each do |model|
+                name = model.to_s.split('::')[-1]
+                result[name] = {
+                  id: name,
+                  name: name,
+                  properties: model.documentation
+                }
+              end
+              result
+            end
+
             def parse_http_codes codes
               codes ||= {}
               codes.collect do |k, v|

spec/api_models_spec.rb

@@ -0,0 +1,76 @@
+require 'spec_helper'
+
+describe "API Models" do
+
+  before :all do
+    module Entities
+      class Something < Grape::Entity
+        expose :text, :documentation => { :type => "string", :desc => "Content of something." }
+      end
+    end
+
+    class ModelsApi < Grape::API
+      format :json
+      desc 'This gets something.', {
+        entity: Entities::Something
+      }
+      get '/something' do
+        something = OpenStruct.new text: 'something'
+        present something, with: Entities::Something
+      end
+      add_swagger_documentation
+    end
+  end
+
+  def app; ModelsApi; end
+
+  it "should document specified models" do
+    get '/swagger_doc'
+    JSON.parse(last_response.body).should == {
+      "apiVersion" => "0.1",
+      "swaggerVersion" => "1.1",
+      "basePath" => "http://example.org",
+      "operations" => [],
+      "apis" => [
+        { "path" => "/swagger_doc/something.{format}" },
+        { "path" => "/swagger_doc/swagger_doc.{format}" }
+      ]
+    }
+  end
+
+  it "should include response_class when specified" do
+    get '/swagger_doc/something.json'
+    JSON.parse(last_response.body).should == {
+      "apiVersion" => "0.1",
+      "swaggerVersion" => "1.1",
+      "basePath" => "http://example.org",
+      "resourcePath" => "",
+      "apis" => [
+        { "path" => "/something.{format}",
+          "operations" => [
+            { "notes" => nil,
+              "responseClass" => "Something",
+              "summary" => "This gets something.",
+              "nickname" => "GET-something---format-",
+              "httpMethod" => "GET",
+              "parameters" => []
+            }
+          ]
+        }
+      ],
+      "models" => {
+        "Something" => {
+          "id" => "Something",
+          "name" => "Something",
+          "properties" => {
+            "text" => {
+              "type" => "string",
+              "desc" => "Content of something."
+            }
+          }
+        }
+      }
+    }
+  end
+
+end

spec/spec_helper.rb

@@ -4,6 +4,7 @@
 
 require 'grape'
 require 'grape-swagger'
+require 'grape-entity'
 
 require 'rubygems'
 require 'bundler'