issue #533: allows to overwrite defaults status codes

Author: LeFnord

.rubocop_todo.yml

@@ -18,7 +18,7 @@ Metrics/BlockLength:
 # Offense count: 3
 # Configuration parameters: CountComments.
 Metrics/ClassLength:
-  Max: 240
+  Max: 247
 
 # Offense count: 10
 Metrics/CyclomaticComplexity:

README.md

@@ -404,6 +404,7 @@ add_swagger_documentation \
 * [Hiding parameters](#hiding-parameters)
 * [Setting a Swagger default value](#default-value)
 * [Response documentation](#response)
+* [Changing default status codes](#change-status)
 * [Extensions](#extensions)
 
 
@@ -752,7 +753,7 @@ You can also document the HTTP status codes with a description and a specified m
 In the following cases, the schema ref would be taken from route.
 
 ```ruby
-desc 'thing', failures: [ { code: 400, message: "Invalid parameter entry" } ]
+desc 'thing', failures: [ { code: 400, message: 'Invalid parameter entry' } ]
 get '/thing' do
   ...
 end
@@ -761,7 +762,7 @@ end
 ```ruby
 desc 'thing' do
   params Entities::Something.documentation
-  failures [ { code: 400, message: "Invalid parameter entry" } ]
+  failures [ { code: 400, message: 'Invalid parameter entry' } ]
 end
 get '/thing' do
   ...
@@ -770,8 +771,8 @@ end
 
 ```ruby
 get '/thing', failures: [
-  { code: 200, message: 'Ok' },
-  { code: 400, message: "Invalid parameter entry" }
+  { code: 400, message: 'Invalid parameter entry' },
+  { code: 404, message: 'Not authorized' },
 ] do
   ...
 end
@@ -780,13 +781,13 @@ end
 By adding a `model` key, e.g. this would be taken.
 ```ruby
 get '/thing', failures: [
-  { code: 200, message: 'Ok' },
-  { code: 422, message: "Invalid parameter entry", model: Entities::ApiError }
+  { code: 400, message: 'General error' },
+  { 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.
+If no status code is defined [defaults](/lib/grape-swagger/endpoint.rb#L210) would be taken.
 
 The result is then something like following:
 
@@ -807,6 +808,33 @@ The result is then something like following:
 },
 ```
 
+<a name="change-status" />
+#### Changing default status codes
+
+The default status codes, one could be found (-> [status codes](lib/grape-swagger/doc_methods/status_codes.rb)) can be changed to your specific needs, to achive it, you have to change it for grape itself and for the documentation.
+
+```ruby
+desc 'Get a list of stuff',
+    success: { code: 202, model: Entities::UseResponse, message: 'a changed status code' }
+get do
+  status 202
+  # your code comes here
+end
+…
+```
+
+```json
+"responses": {
+  "202": {
+    "description": "ok",
+    "schema": {
+      "$ref": "#/definitions/UseResponse"
+    }
+  }
+},
+```
+
+
 <a name="extensions" />
 #### Extensions
 

lib/grape-swagger/doc_methods/status_codes.rb

@@ -8,6 +8,8 @@ def get
             post: { code: 201, message: 'created {item}' },
             put: { code: 200, message: 'updated {item}' },
             patch: { code: 200, message: 'patched {item}' },
+            # 200 for delete would only be used, if a success entity is given,
+            # else it would be set to 204
             delete: { code: 200, message: 'deleted {item}' },
             head: { code: 200, message: 'head {item}' },
             options: { code: 200, message: 'option {item}' }

lib/grape-swagger/endpoint.rb

@@ -178,8 +178,8 @@ def params_object(route)
 
     def response_object(route, markdown)
       codes = (route.http_codes || route.options[:failure] || [])
-      codes = apply_defaults(route, codes) if route.options[:ignore_defaults].nil?
 
+      codes = apply_success_codes(route) + codes
       codes.map! { |x| x.is_a?(Array) ? { code: x[0], message: x[1], model: x[2] } : x }
 
       codes.each_with_object({}) do |value, memo|
@@ -207,11 +207,19 @@ def response_object(route, markdown)
       end
     end
 
-    def apply_defaults(route, codes)
+    def apply_success_codes(route)
       default_code = GrapeSwagger::DocMethods::StatusCodes.get[route.request_method.downcase.to_sym]
-      default_code[:model] = @entity if @entity
-      default_code[:message] = route.description || default_code[:message].sub('{item}', @item)
-      [default_code] + codes
+      if @entity.is_a?(Hash)
+        default_code[:code] = @entity[:code] if @entity[:code].present?
+        default_code[:model] = @entity[:model] if @entity[:model].present?
+        default_code[:message] = @entity[:message] || route.description || default_code[:message].sub('{item}', @item)
+      else
+        default_code = GrapeSwagger::DocMethods::StatusCodes.get[route.request_method.downcase.to_sym]
+        default_code[:model] = @entity if @entity
+        default_code[:message] = route.description || default_code[:message].sub('{item}', @item)
+      end
+
+      [default_code]
     end
 
     def tag_object(route)

spec/issues/533_specify_status_code_spec.rb

@@ -0,0 +1,68 @@
+require 'spec_helper'
+
+describe '#533 specify status codes' do
+  include_context "#{MODEL_PARSER} swagger example"
+
+  let(:app) do
+    Class.new(Grape::API) do
+      namespace :issue_533 do
+        desc 'Get a list of stuff',
+             success: { code: 202, model: Entities::UseResponse, message: 'a changed status code' }
+        get do
+          status 202
+          { foo: 'that is the response' }
+        end
+
+        desc 'Post some stuff',
+             success: { code: 202, model: Entities::UseResponse, message: 'a changed status code' }
+        post do
+          status 202
+          { foo: 'that is the response' }
+        end
+
+        desc 'Post some stuff',
+             success: { code: 204, message: 'a changed status code' }
+        patch do
+          status 204
+        end
+
+        desc 'Delete some stuff',
+             success: { code: 203 }
+        delete do
+          status 203
+        end
+      end
+
+      add_swagger_documentation format: :json
+    end
+  end
+
+  subject do
+    get '/swagger_doc'
+    JSON.parse(last_response.body)['paths']['/issue_533']
+  end
+
+  let(:get_response) { subject['get']['responses'] }
+  specify do
+    expect(get_response.keys.first).to eql '202'
+    expect(get_response['202']).to include 'schema'
+  end
+
+  let(:post_response) { subject['post']['responses'] }
+  specify do
+    expect(post_response.keys.first).to eql '202'
+    expect(post_response['202']).to include 'schema'
+  end
+
+  let(:patch_response) { subject['patch']['responses'] }
+  specify do
+    expect(patch_response.keys.first).to eql '204'
+    expect(patch_response['204']).not_to include 'schema'
+  end
+
+  let(:delete_response) { subject['delete']['responses'] }
+  specify do
+    expect(delete_response.keys.first).to eql '203'
+    expect(delete_response['203']).not_to include 'schema'
+  end
+end

spec/swagger_v2/api_swagger_v2_ignore_defaults_spec.rb

@@ -8,12 +8,12 @@ def app
       format :json
 
       desc 'This creates Thing after a delay',
-           success: Entities::Something
+           success: { code: 202, message: 'OK', model: Entities::Something }
       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 '/delay_thing', http_codes: [{ code: 202, message: 'OK' }], ignore_defaults: true do
+      post '/delay_thing' do
         status 202
       end
 
@@ -40,7 +40,7 @@ def app
   let(:json) { JSON.parse(last_response.body) }
 
   it 'only returns one response if ignore_defaults is specified' do
-    expect(json['paths']['/delay_thing']['post']['responses']).to eq('202' => { 'description' => 'OK' })
+    expect(json['paths']['/delay_thing']['post']['responses']).to eq('202' => { 'description' => 'OK', 'schema' => { '$ref' => '#/definitions/Something' } })
     expect(json['paths']['/delay_thing']['post']['responses'].keys).not_to include '201'
   end
 end