Add 'deprecated' and updated CHANGELOG and README

.rubocop_todo.yml

@@ -28,7 +28,7 @@ Metrics/AbcSize:
 # Offense count: 3
 # Configuration parameters: CountComments.
 Metrics/ClassLength:
-  Max: 206
+  Max: 210
 
 # Offense count: 10
 Metrics/CyclomaticComplexity:

CHANGELOG.md

@@ -2,12 +2,10 @@
 
 #### Features
 
-* Your contribution here.
+* [#431](https://github.com/ruby-grape/grape-swagger/pull/431): Add summary and deprecated to the operation object generator to be more compliant with [OpenAPI v2](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operation-object) - [@aschuster3](https://github.com/aschuster3)
 
 #### Fixes
 
-* Your contribution here.
-
 ### 0.20.4 (May 16, 2016)
 
 #### Features

README.md

@@ -442,6 +442,52 @@ end
 ```
 
 
+#### Overriding the route summary
+
+By default, the route summary is filled with the value supplied to `desc`.
+
+```ruby
+namespace 'order' do
+  desc 'This will be your summary'
+  get :order_id do
+    ...
+  end
+end
+```
+
+To override the summary, add `summary: '[string]'` after the description.
+
+```ruby
+namespace 'order' do
+  desc 'This will be your summary',
+    summary: 'Now this is your summary!'
+  get :order_id do
+    ...
+  end
+end
+```
+
+
+#### Deprecate routes
+
+For route deprecation, add `deprecated: true` after your description.
+
+```ruby
+namespace 'order' do
+  desc 'Old way to do things',
+    deprecated: true
+  get :old do
+    ...
+  end
+
+  desc 'New way to do things'
+  get :new do
+    ...
+  end
+end
+```
+
+
 #### Expose nested namespace as standalone route
 
 Use the `nested: false` property in the `swagger` option to make nested namespaces appear as standalone resources.

lib/grape-swagger/endpoint.rb

@@ -102,7 +102,6 @@ def path_item(routes, options)
     end
 
     def method_object(route, options, path)
-      puts "lib/grape-swagger/endpoint.rb:105 DEBUG OUTPUT FOR GRAPE-SWAGGER: #{route.options}"
       method = {}
       method[:summary]     = summary_object(route)
       method[:description] = description_object(route, options[:markdown])
@@ -111,6 +110,7 @@ def method_object(route, options, path)
       method[:parameters]  = params_object(route)
       method[:responses]   = response_object(route, options[:markdown])
       method[:tags]        = tag_object(route, options[:version].to_s)
+      method[:deprecated]  = deprecated_object(route)
       method[:operationId] = GrapeSwagger::DocMethods::OperationId.build(route, path)
       method.delete_if { |_, value| value.blank? }
 
@@ -199,6 +199,10 @@ def tag_object(route, version)
       Array(route.path.split('{')[0].split('/').reject(&:empty?).delete_if { |i| ((i == route.prefix.to_s) || (i == version)) }.first)
     end
 
+    def deprecated_object(route)
+      route.options.key?(:deprecated) && route.options[:deprecated]
+    end
+
     private
 
     def partition_params(route)

spec/support/model_parsers/entity_parser.rb

@@ -292,7 +292,6 @@ class RecursiveModel < Grape::Entity
         'QueryInput' => {
           'type' => 'object',
           'properties' => { 'elements' => { 'type' => 'array', 'items' => { '$ref' => '#/definitions/QueryInputElement' }, 'description' => 'Set of configuration' } },
-          'summary' => 'nested route inside namespace',
           'description' => 'nested route inside namespace'
         },
         'QueryInputElement' => {
@@ -302,7 +301,6 @@ class RecursiveModel < Grape::Entity
         'ApiError' => {
           'type' => 'object',
           'properties' => { 'code' => { 'type' => 'integer', 'format' => 'int32', 'description' => 'status code' }, 'message' => { 'type' => 'string', 'description' => 'error message' } },
-          'summary' => 'This gets Things.',
           'description' => 'This gets Things.'
         },
         'Something' => {
@@ -313,7 +311,6 @@ class RecursiveModel < Grape::Entity
             'links' => { 'type' => 'link' },
             'others' => { 'type' => 'text' }
           },
-          'summary' => 'This gets Things.',
           'description' => 'This gets Things.'
         }
       }

spec/support/model_parsers/representable_parser.rb

@@ -361,7 +361,6 @@ class RecursiveModel < Representable::Decorator
         'QueryInput' => {
           'type' => 'object',
           'properties' => { 'elements' => { 'type' => 'array', 'items' => { '$ref' => '#/definitions/QueryInputElement' }, 'description' => 'Set of configuration' } },
-          'summary' => 'nested route inside namespace',
           'description' => 'nested route inside namespace'
         },
         'QueryInputElement' => {
@@ -371,7 +370,6 @@ class RecursiveModel < Representable::Decorator
         'ApiError' => {
           'type' => 'object',
           'properties' => { 'code' => { 'type' => 'integer', 'format' => 'int32', 'description' => 'status code' }, 'message' => { 'type' => 'string', 'description' => 'error message' } },
-          'summary' => 'This gets Things.',
           'description' => 'This gets Things.'
         },
         'Something' => {
@@ -382,7 +380,6 @@ class RecursiveModel < Representable::Decorator
             'links' => { 'type' => 'array', 'items' => { 'description' => '', 'type' => 'link' } },
             'others' => { 'description' => '', 'type' => 'text' }
           },
-          'summary' => 'This gets Things.',
           'description' => 'This gets Things.'
         }
       }

spec/swagger_v2/api_swagger_v2_deprecation_spec.rb

@@ -0,0 +1,46 @@
+require 'spec_helper'
+
+describe 'swagger spec v2.0 deprecation' do
+  include_context "#{MODEL_PARSER} swagger example"
+
+  def app
+    Class.new(Grape::API) do
+      format :json
+
+      desc 'This is a test sample', deprecated: true
+      get '/old' do
+        present true
+      end
+
+      desc 'This is another test sample', deprecated: false
+      get '/new' do
+        present true
+      end
+
+      version 'v1', using: :path
+      add_swagger_documentation api_version: 'v1',
+                                base_path: '/api',
+                                info: {
+                                  title: 'The API title to be displayed on the API homepage.',
+                                  description: 'A description of the API.',
+                                  contact_name: 'Contact name',
+                                  contact_email: 'Contact@email.com',
+                                  contact_url: 'Contact URL',
+                                  license: 'The name of the license.',
+                                  license_url: 'www.The-URL-of-the-license.org',
+                                  terms_of_service_url: 'www.The-URL-of-the-terms-and-service.com'
+                                }
+    end
+  end
+
+  before do
+    get '/v1/swagger_doc'
+  end
+
+  let(:json) { JSON.parse(last_response.body) }
+
+  describe 'deprecation' do
+    it { expect(json['paths']['/old']['get']['deprecated']).to eql true }
+    it { expect(json['paths']['/new']['get']).to_not include 'deprecated' }
+  end
+end