WIP: swagger2.0: adds schema to response

Peter Scholz · Peter Scholz · commit 9186d70b7ab4 · 2015-09-25T14:15:49.000+02:00
diff --git a/README.md b/README.md
@@ -504,8 +504,9 @@ end
 
 ## Response documentation
 
-You can also document the HTTP status codes with a description ~~and a specified model~~ that your API returns with one of the following syntax.
+You can also document the HTTP status codes with a description and a specified model, as ref in the schema to the definitions, that your API returns with one of the following syntax.
 
+In the following cases, the schema ref would be taken from route.
 ``` ruby
 desc 'thing', http_codes: [ { code: 400, message: "Invalid parameter entry" } ]
 get '/thing' do
@@ -524,16 +525,44 @@ end
 ```
 
 ``` ruby
-get '/', http_codes: [
+get '/thing', http_codes: [
   { code: 200, message: 'Ok' },
   { code: 400, message: "Invalid parameter entry" }
 ] do
   ...
 end
 ```
 
+By adding a `model` key, e.g. this would be taken.
+``` ruby
+get '/thing', http_codes: [
+  { code: 200, message: 'Ok' },
+  { code: 422, message: "Invalid parameter entry", model: Entities::ApiError }
+] do
+  ...
+end
+```
+
 If no status code is defined [defaults](/lib/grape-swagger/endpoint.rb#L121) would be taken.
 
+The result is then something like following:
+
+```json
+"responses": {
+  "200": {
+    "description": "get Horses",
+    "schema": {
+      "$ref": "#/definitions/Thing"
+    }
+  },
+  "401": {
+    "description": "HorsesOutError",
+    "schema": {
+      "$ref": "#/definitions/ApiError"
+    }
+  }
+},
+```
 
 ## Contributing to grape-swagger
 
diff --git a/lib/grape-swagger/endpoint.rb b/lib/grape-swagger/endpoint.rb
@@ -115,7 +115,21 @@ def method_object(method, route, options)
 
     def response_object(route)
       codes = default_staus_codes[route.route_method.downcase.to_sym] + (route.route_http_codes || [])
-      codes.inject({}) {|h, v| h[v[:code]] = {description: v[:message].sub('{item}',@item)}; h }
+
+      codes.map!{|x| x.is_a?(Array)? {code: x[0], message: x[1], model: x[2].to_s} : x }
+
+      codes.inject({}) do |h, v|
+        h[v[:code]] = { description: v[:message].sub('{item}',@item) }
+
+        response_model = @item
+        response_model = expose_params_from_model(v[:model]) if v[:model]
+
+        # TODO: proof that the definition exist, if model isn't specified
+        unless response_model.start_with?('Swagger_doc')
+          h[v[:code]][:schema] = { '$ref' => "#/definitions/#{response_model}" }
+        end
+        h
+      end
     end
 
     def default_staus_codes
@@ -158,6 +172,19 @@ def parse_expose_params(params, route)
       @definitions[@item] = {properties: properties}
     end
 
+    def expose_params_from_model(model)
+      model_name = model.name.split('::').last
+
+      properties = model.documentation.inject({}) do |h,x|
+        h[x.first] = {type: data_type(x.last)}
+        h[x.first][:enum] = x.last[:values] if x.last[:values] && x.last[:values].is_a?(Array)
+        h
+      end
+      @definitions[model_name] = {properties: properties}
+
+      model_name
+    end
+
     def parse_request_params(param, value, path, method)
       items = {}
 
diff --git a/spec/api_swagger_v2_spec.rb b/spec/api_swagger_v2_spec.rb
@@ -13,7 +13,7 @@ class Something < Grape::Entity
 
         class EnumValues < Grape::Entity
           expose :gender, documentation: { type: 'string', desc: 'Content of something.', values: %w(Male Female) }
-          expose :number, documentation: { type: 'integer', desc: 'Content of something.', values: proc { [1, 2] } }
+          expose :number, documentation: { type: 'integer', desc: 'Content of something.', values: [1, 2]  }
         end
 
         class ComposedOf < Grape::Entity
@@ -76,6 +76,12 @@ class ThingWithRoot < Grape::Entity
           root 'things', 'thing'
           expose :text, documentation: { type: 'string', desc: 'Content of something.' }
         end
+
+        class ApiError < Grape::Entity
+          expose :code, documentation: { type: Integer, desc: 'status code' }
+          expose :message, documentation: { type: String, desc: 'error message' }
+        end
+
       end
 
     end
@@ -84,62 +90,74 @@ def app
       Class.new(Grape::API) do
         format :json
 
-        # # Something stuff
-        # desc 'This gets Somethings.', entity: Entities::Something, params: Entities::Something.documentation
-        # get '/something' do
-        #   something = OpenStruct.new text: 'something'
-        #   present something, with: Entities::Something
-        # end
-        #
-        # desc 'This gets Something.', entity: Entities::Something, params: Entities::Something.documentation
-        # params do
-        #   requires :id, type: Integer, desc: 'Identity'
-        # end
-        # get '/something/:id' do
-        #   something = OpenStruct.new text: 'something'
-        #   present something, with: Entities::Something
-        # end
-        #
-        # desc 'This creates Something.', entity: Entities::Something, params: Entities::Something.documentation
-        # params do
-        #   requires :text, type: String, documentation: { type: 'string', desc: 'Content of something.' }
-        #   requires :links, type: Array, documentation: { type: 'link', is_array: true }
-        # end
-        # post '/something' do
-        #   something = OpenStruct.new text: 'something'
-        #   present something, with: Entities::Something
-        # end
-        #
-        # desc 'This updates Something.', entity: Entities::Something, params: Entities::Something.documentation
-        # params do
-        #   requires :id, type: Integer
-        #   optional :text, type: String, documentation: { type: 'string', desc: 'Content of something.' }
-        #   optional :links, type: Array, documentation: { type: 'link', is_array: true }
-        # end
-        # put '/something/:id' do
-        #   something = OpenStruct.new text: 'something'
-        #   present something, with: Entities::Something
-        # end
-        #
-        # desc 'This deletes something.', entity: Entities::Something, params: Entities::Something.documentation
-        # params do
-        #   requires :id, type: Integer
-        # end
-        # delete '/something/:id' do
-        #   something = OpenStruct.new text: 'something'
-        #   present something, with: Entities::Something
-        # end
+        # Something stuff
+        desc 'This gets Somethings.', entity: Entities::Something, params: Entities::Something.documentation
+        get '/something' do
+          something = OpenStruct.new text: 'something'
+          present something, with: Entities::Something
+        end
+
+        desc 'This gets Something.', entity: Entities::Something, params: Entities::Something.documentation
+        params do
+          requires :id, type: Integer, desc: 'Identity'
+        end
+        get '/something/:id' do
+          something = OpenStruct.new text: 'something'
+          present something, with: Entities::Something
+        end
+
+        desc 'This creates Something.', entity: Entities::Something, params: Entities::Something.documentation
+        params do
+          requires :text, type: String, documentation: { type: 'string', desc: 'Content of something.' }
+          requires :links, type: Array, documentation: { type: 'link', is_array: true }
+        end
+        post '/something' do
+          something = OpenStruct.new text: 'something'
+          present something, with: Entities::Something
+        end
+
+        desc 'This updates Something.', entity: Entities::Something, params: Entities::Something.documentation
+        params do
+          requires :id, type: Integer
+          optional :text, type: String, documentation: { type: 'string', desc: 'Content of something.' }
+          optional :links, type: Array, documentation: { type: 'link', is_array: true }
+        end
+        put '/something/:id' do
+          something = OpenStruct.new text: 'something'
+          present something, with: Entities::Something
+        end
+
+        desc 'This deletes something.', entity: Entities::Something, params: Entities::Something.documentation
+        params do
+          requires :id, type: Integer
+        end
+        delete '/something/:id' do
+          something = OpenStruct.new text: 'something'
+          present something, with: Entities::Something
+        end
 
         #  Thing stuff
         desc 'This gets Things.' do
           params Entities::Something.documentation
-          http_codes [ { code: 401, message: 'Unauthorized' } ]
+          http_codes [ { code: 401, message: 'Unauthorized', model: Entities::ApiError } ]
         end
         get '/thing' do
           something = OpenStruct.new text: 'something'
           present something, with: Entities::Something
         end
 
+        desc 'This gets Things.' do
+          params Entities::Something.documentation
+          http_codes [
+            { code: 200, message: 'get Horses', model: Entities::EnumValues },
+            { code: 401, message: 'HorsesOutError', model: Entities::ApiError }
+          ]
+        end
+        get '/thing2' do
+          something = OpenStruct.new text: 'something'
+          present something, with: Entities::Something
+        end
+
         desc 'This gets Thing.' do
           params Entities::Something.documentation
           http_codes [ { code: 200, message: 'getting a single thing' }, { code: 401, message: 'Unauthorized' } ]
