grape-swagger 0.28.0 → 0.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d425dcb8ef7eb5f98bba7c012f624b7cfd0052e91a5b3f7f5d7374c7d7529b2
-  data.tar.gz: 83c9d09cc29e30b73a263fdc66eaffe587a9503efcbf2b427cb1dd46280ed7e2
+  metadata.gz: 3fd414192a99ad92ea5ebdc015373059ab02819a7512119897a6fa71f309c083
+  data.tar.gz: 8ed9bd4a2fcb9d8e07b86aa899bf5ca7da74d716c8e45bf90667741abeedb718
 SHA512:
-  metadata.gz: 5d4f19f682ba1a5f999429ec3568107b8873ada3c9e033363d90be6d669e653f16ea7ac1da116bd1702326c4dc5ed65746819d34fb67ca41cbfd2cc0611dbe4d
-  data.tar.gz: 022cdcba56eb3e8c9bf38c406851b40546053bb170204e429a92d218e96ad7a1fc507802eb5f90bb8d8b77e1a5509e63a54a4a27424db1b95b1b62a9e4e5c667
+  metadata.gz: 7abb761a0965db3a41dca82d2a72a451f95c2e5a13cfaaede2603c8312cb9077499ca446e1b551f308ecb293a8c2b3c8c1fad7aa378e674457848e817b84e934
+  data.tar.gz: f284e5a252115e1b0d673ec07ec4b2ace2371b001cdf62e4d9e48331e0f115547ec2ee659ccba2a2d1fdc7f868c1c0ecfb1f5c341e84f1f6f7369782a4eb4f58

data/.rubocop_todo.yml

@@ -21,7 +21,7 @@ Metrics/AbcSize:
 # Offense count: 3
 # Configuration parameters: CountComments.
 Metrics/ClassLength:
-  Max: 280
+  Max: 287
 
 # Offense count: 10
 Metrics/CyclomaticComplexity:

data/.travis.yml

@@ -11,33 +11,29 @@ after_success:
   - bundle exec danger
 
 rvm:
-  - 2.5.0
-  - 2.4.3
-
+  - 2.5.1
+  - 2.4.4
 env:
   - MODEL_PARSER=grape-swagger-entity
   - MODEL_PARSER=grape-swagger-representable
   - GRAPE_VERSION=0.17.0
   - GRAPE_VERSION=0.18.0
   - GRAPE_VERSION=0.19.2
-  - GRAPE_VERSION=1.0.1
+  - GRAPE_VERSION=1.0.3
   - GRAPE_VERSION=HEAD
 
 matrix:
   fast_finish: true
 
   include:
-    - rvm: 2.3.6
+    - rvm: 2.3.7
       env:
     - rvm: ruby-head
       env:
     - rvm: jruby-head
       env:
-    - rvm: rbx-3
-      env:
 
   allow_failures:
-    - rvm: 2.3.6
+    - rvm: 2.3.7
     - rvm: ruby-head
     - rvm: jruby-head
-    - rvm: rbx-3

data/CHANGELOG.md

@@ -8,6 +8,20 @@
 
 * Your contribution here.
 
+###  0.29.0 (May 22, 2018)
+
+#### Features
+
+* [#667](https://github.com/ruby-grape/grape-swagger/pull/667): Make route summary optional - [@obduk](https://github.com/obduk).
+* [#670](https://github.com/ruby-grape/grape-swagger/pull/670): Add support for deprecated field - [@ioanatia](https://github.com/ioanatia).
+* [#675](https://github.com/ruby-grape/grape-swagger/pull/675): Add response examples - [@gamartin](https://github.com/gamartin).
+
+#### Fixes
+
+* [#664](https://github.com/ruby-grape/grape-swagger/pull/662): Removed all references to obsolete `hide_format` parameter - [@jonmchan](https://github.com/jonmchan).
+* [#669](https://github.com/ruby-grape/grape-swagger/pull/669): Fix handling of http status codes from routes - [@milgner](https://github.com/milgner).
+* [#672](https://github.com/ruby-grape/grape-swagger/pull/672): Rename 'notes' to 'detail' in README - [@kjleitz](https://github.com/kjleitz).
+
 ### 0.28.0 (February 3, 2018)
 
 #### Features

data/README.md

@@ -334,7 +334,7 @@ add_swagger_documentation \
 ```
 
 
-### tags: <a name="tags" />
+#### tags: <a name="tags" />
 A list of tags to document.  By default tags are automatically generated
 for endpoints based on route names.
 
@@ -372,26 +372,6 @@ add_swagger_documentation \
 
 A hash merged into the `info` key of the JSON documentation.
 
-<!-- #### *authorizations*:
-This value is added to the `authorizations` key in the JSON documentation. -->
-
-<!-- #### *api_documentation*:
-Customize the Swagger API documentation route, typically contains a `desc` field. The default description is "Swagger compatible API description".
-
-```ruby
-add_swagger_documentation \
-   api_documentation: { desc: 'Reticulated splines API swagger-compatible documentation.' }
-```
-
-
-#### *specific_api_documentation*:
-Customize the Swagger API specific documentation route, typically contains a `desc` field. The default description is "Swagger compatible API description for specific API".
-
-```ruby
-add_swagger_documentation \
-   specific_api_documentation: { desc: 'Reticulated splines API swagger-compatible endpoint documentation.' }
-``` -->
-
 
 
 ## Routes Configuration <a name="routes" />
@@ -402,6 +382,8 @@ add_swagger_documentation \
 * [Specify endpoint details](#details)
 * [Overriding the route summary](#summary)
 * [Overriding the tags](#tags)
+* [Deprecating routes](#deprecating-routes)
+* [Overriding the name of the body parameter](#body-param)
 * [Defining an endpoint as an array](#array)
 * [Using an options hash](#options)
 * [Overriding parameter type](#overriding-param-type)
@@ -415,11 +397,10 @@ add_swagger_documentation \
 * [Changing default status codes](#change-status)
 * [File response](#file-response)
 * [Extensions](#extensions)
-
-
+* [Response examples documentation](#response-examples)
 
 #### Swagger Header Parameters  <a name="headers" />
- <a name="headers" />
+
 Swagger also supports the documentation of parameters passed in the header. Since grape's ```params[]``` doesn't return header parameters we can specify header parameters seperately in a block after the description.
 
 ```ruby
@@ -438,7 +419,6 @@ desc "Return super-secret information", {
 ```
 
 
-
 #### Hiding an Endpoint <a name="hiding" />
 
 You can hide an endpoint by adding ```hidden: true``` in the description of the endpoint:
@@ -468,7 +448,6 @@ desc 'Conditionally hide this endpoint', hidden: lambda { ENV['EXPERIMENTAL'] !=
 ```
 
 
-
 #### Overriding Auto-Generated Nicknames <a name="overriding-auto-generated-nicknames" />
 
 You can specify a swagger nickname to use instead of the auto generated name by adding `:nickname 'string'``` in the description of the endpoint.
@@ -478,7 +457,6 @@ desc 'Get a full list of pets', nickname: 'getAllPets'
 ```
 
 
-
 #### Specify endpoint details <a name="details" />
 
 To specify further details for an endpoint, use the `detail` option within a block passed to `desc`:
@@ -491,7 +469,6 @@ get '/kittens' do
 ```
 
 
-
 #### Overriding the route summary <a name="summary" />
 
 To override the summary, add `summary: '[string]'` after the description.
@@ -507,7 +484,6 @@ end
 ```
 
 
-
 #### Overriding the tags <a name="tags" />
 
 Tags are used for logical grouping of operations by resources or any other qualifier. To override the
@@ -523,7 +499,21 @@ end
 ```
 
 
-#### Overriding the name of the body parameter
+#### Deprecating routes <a name="deprecating-routes" />
+
+To deprecate a route add `deprecated: true` after the description.
+
+```ruby
+namespace 'order' do
+  desc 'This is a deprecated route', deprecated: true
+  get :order_id do
+    ...
+  end
+end
+```
+
+
+#### Overriding the name of the body parameter  <a name="body-param" />
 
 By default, body parameters have a generated name based on the operation. For
 deeply nested resources, this name can get very long. To override the name of
@@ -538,6 +528,7 @@ namespace 'order' do
 end
 ```
 
+
 #### Defining an endpoint as an array <a name="array" />
 
 You can define an endpoint as an array by adding `is_array` in the description:
@@ -547,7 +538,6 @@ desc 'Get a full list of pets', is_array: true
 ```
 
 
-
 #### Using an options hash <a name="options" />
 
 The Grape DSL supports either an options hash or a restricted block to pass settings. Passing the `nickname`, `hidden` and `is_array` options together with response codes is only possible when passing an options hash.
@@ -568,7 +558,6 @@ get '/kittens' do
 ```
 
 
-
 #### Overriding parameter type <a name="overriding-param-type" />
 
 You can override paramType, using the documentation hash. See [parameter object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameter-object) for available types.
@@ -583,7 +572,6 @@ end
 ```
 
 
-
 #### Overriding data type of the parameter <a name="overriding-type-of-param" />
 
 You can override type, using the documentation hash.
@@ -608,7 +596,6 @@ end
 ```
 
 
-
 #### Multiple types <a name="multiple-types" />
 
 By default when you set multiple types, the first type is selected as swagger type
@@ -632,7 +619,6 @@ end
 ```
 
 
-
 #### Array of data type <a name="array-type" />
 
 Array types are also supported.
@@ -659,7 +645,6 @@ end
 ```
 
 
-
 #### Collection format of arrays <a name="collection-format" />
 
 You can set the collection format of an array, using the documentation hash.
@@ -694,7 +679,6 @@ end
 ```
 
 
-
 #### Hiding parameters <a name="hiding-parameters" />
 
 Exclude single optional parameter from the documentation
@@ -710,7 +694,6 @@ end
 ```
 
 
-
 #### Setting a Swagger default value <a name="default-value" />
 
 Grape allows for an additional documentation hash to be passed to a parameter.
@@ -781,7 +764,6 @@ end
 ```
 
 
-
 #### Response documentation <a name="response" />
 
 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.
@@ -1001,6 +983,60 @@ route_setting :x_def, [{ for: 422, other: 'stuff' }, { for: 200, some: 'stuff' }
 ```
 
 
+#### Response examples documentation <a name="response-examples" />
+
+You can also add examples to your responses by using the `desc` DSL with block syntax.
+
+By specifying examples to `success` and `failure`.
+
+```ruby
+desc 'This returns examples' do
+  success model: Thing, examples: { 'application/json' => { description: 'Names list', items: [{ id: '123', name: 'John' }] } }
+  failure [[404, 'NotFound', ApiError, { 'application/json' => { code: 404, message: 'Not found' } }]]
+end
+get '/thing' do
+  ...
+end
+```
+
+The result will look like following:
+
+```json
+  "responses": {
+    "200": {
+      "description": "This returns examples",
+      "schema": {
+        "$ref": "#/definitions/Thing"
+      },
+      "examples": {
+        "application/json": {
+          "description": "Names list",
+          "items": [
+            {
+              "id": "123",
+              "name": "John"
+            }
+          ]
+        }
+      }
+    },
+    "404": {
+      "description": "NotFound",
+      "schema": {
+        "$ref": "#/definitions/ApiError"
+      },
+      "examples": {
+        "application/json": {
+          "code": 404,
+          "message": "Not found"
+        }
+      }
+    }
+  }
+```
+
+Failure information can be passed as an array of arrays or an array of hashes.
+
 
 ## Using Grape Entities <a name="grape-entity" />
 
@@ -1122,8 +1158,8 @@ end
 ```
 
 
-## Securing the Swagger UI <a name="oauth" />
 
+## Securing the Swagger UI <a name="oauth" />
 
 The Swagger UI on Grape could be secured from unauthorized access using any middleware, which provides certain methods:
 
@@ -1145,7 +1181,6 @@ This is how to configure the grape_swagger documentation:
                             title: 'My API',
                             doc_version: '0.0.1',
                             hide_documentation_path: true,
-                            hide_format: true,
                             endpoint_auth_wrapper: WineBouncer::OAuth2, # This is the middleware for securing the Swagger UI
                             swagger_endpoint_guard: 'oauth2 false',     # this is the guard method and scope
                             token_owner: 'resource_owner'               # This is the method returning the owner of the token
@@ -1156,7 +1191,7 @@ The guard method should inject the Security Requirement Object into the endpoint
 The 'oauth2 false' added to swagger_documentation is making the main Swagger endpoint protected with OAuth, i.e. the
 access_token is being retreiving from the HTTP request, but the 'false' scope is for skipping authorization and
 showing the UI for everyone. If the scope would be set to something else, like 'oauth2 admin', for example, than the UI
- wouldn't be displayed at all to unauthorized users.  
+ wouldn't be displayed at all to unauthorized users.
 
 Further on, the guard could be used, where necessary, for endpoint access protection. Put it prior to the endpoint's method:
 
@@ -1193,6 +1228,7 @@ The lambda is checking whether the user is authenticated (if not, the token_owne
 role - only admins can see this endpoint.
 
 
+
 ## Examples <a="example" />
 
 Go into example directory and run it: `$ bundle exec rackup`
@@ -1216,7 +1252,7 @@ class NamespaceApi < Grape::API
     end
 
     desc 'This gets something.',
-      notes: '_test_'
+      detail: '_test_'
 
     get '/simple' do
       { bla: 'something' }

data/grape-swagger.gemspec

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-$LOAD_PATH.push File.expand_path('../lib', __FILE__)
+$LOAD_PATH.push File.expand_path('lib', __dir__)
 require 'grape-swagger/version'
 
 Gem::Specification.new do |s|

data/lib/grape-swagger/endpoint.rb

@@ -123,18 +123,23 @@ module Grape
       method[:responses]   = response_object(route)
       method[:tags]        = route.options.fetch(:tags, tag_object(route, path))
       method[:operationId] = GrapeSwagger::DocMethods::OperationId.build(route, path)
+      method[:deprecated] = deprecated_object(route)
       method.delete_if { |_, value| value.blank? }
 
       [route.request_method.downcase.to_sym, method]
     end
 
+    def deprecated_object(route)
+      route.options[:deprecated] if route.options.key?(:deprecated)
+    end
+
     def security_object(route)
       route.options[:security] if route.options.key?(:security)
     end
 
     def summary_object(route)
       summary = route.options[:desc] if route.options.key?(:desc)
-      summary = route.description if route.description.present?
+      summary = route.description if route.description.present? && route.options.key?(:detail)
       summary = route.options[:summary] if route.options.key?(:summary)
 
       summary
@@ -190,7 +195,7 @@ module Grape
 
     def response_object(route)
       codes = http_codes_from_route(route)
-      codes.map! { |x| x.is_a?(Array) ? { code: x[0], message: x[1], model: x[2] } : x }
+      codes.map! { |x| x.is_a?(Array) ? { code: x[0], message: x[1], model: x[2], examples: x[3] } : x }
 
       codes.each_with_object({}) do |value, memo|
         value[:message] ||= ''
@@ -209,18 +214,19 @@ module Grape
         next unless !response_model.start_with?('Swagger_doc') && (@definitions[response_model] || value[:model])
 
         @definitions[response_model][:description] = description_object(route)
-        # TODO: proof that the definition exist, if model isn't specified
-        reference = { '$ref' => "#/definitions/#{response_model}" }
-        memo[value[:code]][:schema] = if route.options[:is_array] && value[:code] < 300
-                                        { type: 'array', items: reference }
-                                      else
-                                        reference
-                                      end
+
+        memo[value[:code]][:schema] = build_reference(route, value, response_model)
+        memo[value[:code]][:examples] = value[:examples] if value[:examples]
       end
     end
 
+    def success_code?(code)
+      status = code.is_a?(Array) ? code.first : code[:code]
+      status.between?(200, 299)
+    end
+
     def http_codes_from_route(route)
-      if route.http_codes.is_a?(Array) && route.http_codes.any? { |code| code[:code].between?(200, 299) }
+      if route.http_codes.is_a?(Array) && route.http_codes.any? { |code| success_code?(code) }
         route.http_codes.clone
       else
         success_codes_from_route(route) + (route.http_codes || route.options[:failure] || [])
@@ -233,6 +239,7 @@ module Grape
         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)
+        default_code[:examples] = @entity[:examples] if @entity[:examples]
       else
         default_code = GrapeSwagger::DocMethods::StatusCodes.get[route.request_method.downcase.to_sym]
         default_code[:model] = @entity if @entity
@@ -254,6 +261,12 @@ module Grape
 
     private
 
+    def build_reference(route, value, response_model)
+      # TODO: proof that the definition exist, if model isn't specified
+      reference = { '$ref' => "#/definitions/#{response_model}" }
+      route.options[:is_array] && value[:code] < 300 ? { type: 'array', items: reference } : reference
+    end
+
     def file_response?(value)
       value.to_s.casecmp('file').zero? ? true : false
     end
@@ -284,9 +297,8 @@ module Grape
     end
 
     def default_type(params)
-      params.each do |param|
-        param[-1] = param.last == '' ? { required: true, type: 'Integer' } : param.last
-      end
+      default_param_type = { required: true, type: 'Integer' }
+      params.each { |param| param[-1] = param.last == '' ? default_param_type : param.last }
     end
 
     def parse_request_params(params)

data/lib/grape-swagger/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GrapeSwagger
-  VERSION = '0.28.0'
+  VERSION = '0.29.0'
 end

data/spec/spec_helper.rb

@@ -10,7 +10,7 @@ SimpleCov.start do
 end
 Coveralls.wear!
 
-$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
 
 MODEL_PARSER = ENV.key?('MODEL_PARSER') ? ENV['MODEL_PARSER'].to_s.downcase.sub('grape-swagger-', '') : 'mock'
 

data/spec/support/model_parsers/entity_parser.rb

@@ -207,7 +207,6 @@ RSpec.shared_context 'entity swagger example' do
       'paths' => {
         '/v3/other_thing/{elements}' => {
           'get' => {
-            'summary' => 'nested route inside namespace',
             'description' => 'nested route inside namespace',
             'produces' => ['application/json'],
             'parameters' => [{ 'in' => 'body', 'name' => 'elements', 'description' => 'Set of configuration', 'type' => 'array', 'items' => { 'type' => 'string' }, 'required' => true }],
@@ -220,7 +219,6 @@ RSpec.shared_context 'entity swagger example' do
         },
         '/thing' => {
           'get' => {
-            'summary' => 'This gets Things.',
             'description' => 'This gets Things.',
             'produces' => ['application/json'],
             'parameters' => [
@@ -234,7 +232,6 @@ RSpec.shared_context 'entity swagger example' do
             'operationId' => 'getThing'
           },
           'post' => {
-            'summary' => 'This creates Thing.',
             'description' => 'This creates Thing.',
             'produces' => ['application/json'],
             'consumes' => ['application/json'],
@@ -249,7 +246,6 @@ RSpec.shared_context 'entity swagger example' do
         },
         '/thing/{id}' => {
           'get' => {
-            'summary' => 'This gets Thing.',
             'description' => 'This gets Thing.',
             'produces' => ['application/json'],
             'parameters' => [{ 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }],
@@ -258,7 +254,6 @@ RSpec.shared_context 'entity swagger example' do
             'operationId' => 'getThingId'
           },
           'put' => {
-            'summary' => 'This updates Thing.',
             'description' => 'This updates Thing.',
             'produces' => ['application/json'],
             'consumes' => ['application/json'],
@@ -272,7 +267,6 @@ RSpec.shared_context 'entity swagger example' do
             'operationId' => 'putThingId'
           },
           'delete' => {
-            'summary' => 'This deletes Thing.',
             'description' => 'This deletes Thing.',
             'produces' => ['application/json'],
             'parameters' => [{ 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }],
@@ -283,7 +277,6 @@ RSpec.shared_context 'entity swagger example' do
         },
         '/thing2' => {
           'get' => {
-            'summary' => 'This gets Things.',
             'description' => 'This gets Things.',
             'produces' => ['application/json'],
             'responses' => { '200' => { 'description' => 'get Horses', 'schema' => { '$ref' => '#/definitions/Something' } }, '401' => { 'description' => 'HorsesOutError', 'schema' => { '$ref' => '#/definitions/ApiError' } } },
@@ -293,7 +286,6 @@ RSpec.shared_context 'entity swagger example' do
         },
         '/dummy/{id}' => {
           'delete' => {
-            'summary' => 'dummy route.',
             'description' => 'dummy route.',
             'produces' => ['application/json'],
             'parameters' => [{ 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }],

data/spec/support/model_parsers/mock_parser.rb

@@ -199,7 +199,6 @@ RSpec.shared_context 'mock swagger example' do
       'paths' => {
         '/v3/other_thing/{elements}' => {
           'get' => {
-            'summary' => 'nested route inside namespace',
             'description' => 'nested route inside namespace',
             'produces' => ['application/json'],
             'parameters' => [{ 'in' => 'body', 'name' => 'elements', 'description' => 'Set of configuration', 'type' => 'array', 'items' => { 'type' => 'string' }, 'required' => true }],
@@ -212,7 +211,6 @@ RSpec.shared_context 'mock swagger example' do
         },
         '/thing' => {
           'get' => {
-            'summary' => 'This gets Things.',
             'description' => 'This gets Things.',
             'produces' => ['application/json'],
             'parameters' => [
@@ -226,7 +224,6 @@ RSpec.shared_context 'mock swagger example' do
             'operationId' => 'getThing'
           },
           'post' => {
-            'summary' => 'This creates Thing.',
             'description' => 'This creates Thing.',
             'produces' => ['application/json'],
             'consumes' => ['application/json'],
@@ -241,7 +238,6 @@ RSpec.shared_context 'mock swagger example' do
         },
         '/thing/{id}' => {
           'get' => {
-            'summary' => 'This gets Thing.',
             'description' => 'This gets Thing.',
             'produces' => ['application/json'],
             'parameters' => [{ 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }],
@@ -250,7 +246,6 @@ RSpec.shared_context 'mock swagger example' do
             'operationId' => 'getThingId'
           },
           'put' => {
-            'summary' => 'This updates Thing.',
             'description' => 'This updates Thing.',
             'produces' => ['application/json'],
             'consumes' => ['application/json'],
@@ -264,7 +259,6 @@ RSpec.shared_context 'mock swagger example' do
             'operationId' => 'putThingId'
           },
           'delete' => {
-            'summary' => 'This deletes Thing.',
             'description' => 'This deletes Thing.',
             'produces' => ['application/json'],
             'parameters' => [{ 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }],
@@ -275,7 +269,6 @@ RSpec.shared_context 'mock swagger example' do
         },
         '/thing2' => {
           'get' => {
-            'summary' => 'This gets Things.',
             'description' => 'This gets Things.',
             'produces' => ['application/json'],
             'responses' => { '200' => { 'description' => 'get Horses', 'schema' => { '$ref' => '#/definitions/Something' } }, '401' => { 'description' => 'HorsesOutError', 'schema' => { '$ref' => '#/definitions/ApiError' } } },
@@ -285,7 +278,6 @@ RSpec.shared_context 'mock swagger example' do
         },
         '/dummy/{id}' => {
           'delete' => {
-            'summary' => 'dummy route.',
             'description' => 'dummy route.',
             'produces' => ['application/json'],
             'parameters' => [{ 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }],

data/spec/support/model_parsers/representable_parser.rb

@@ -211,7 +211,7 @@ RSpec.shared_context 'representable swagger example' do
     {
       'ApiError' => { 'type' => 'object', 'properties' => { 'code' => { 'description' => 'status code', 'type' => 'integer', 'format' => 'int32' }, 'message' => { 'description' => 'error message', 'type' => 'string' } } },
       'ResponseItem' => { 'type' => 'object', 'properties' => { 'id' => { 'description' => '', 'type' => 'integer', 'format' => 'int32' }, 'name' => { 'description' => '', 'type' => 'string' } } },
-      'UseResponse' => { 'type' => 'object', 'properties' => { 'description' => { 'description' => '', 'type' => 'string' }, 'items' => { 'type' => 'array', 'items' => { '$ref' => '#/definitions/ResponseItem' }, 'description' => '' } } },
+      'UseResponse' => { 'type' => 'object', 'properties' => { 'description' => { 'description' => '', 'type' => 'string' }, '$responses' => { 'type' => 'array', 'items' => { '$ref' => '#/definitions/ResponseItem' }, 'description' => '' } } },
       'RecursiveModel' => { 'type' => 'object', 'properties' => { 'name' => { 'type' => 'string', 'description' => 'The name.' }, 'children' => { 'type' => 'array', 'items' => { '$ref' => '#/definitions/RecursiveModel' }, 'description' => 'The child nodes.' } } }
     }
   end
@@ -227,7 +227,7 @@ RSpec.shared_context 'representable swagger example' do
     {
       'ApiError' => { 'type' => 'object', 'properties' => { 'code' => { 'description' => 'status code', 'type' => 'integer', 'format' => 'int32' }, 'message' => { 'description' => 'error message', 'type' => 'string' } }, 'description' => 'This returns something' },
       'ResponseItem' => { 'type' => 'object', 'properties' => { 'id' => { 'description' => '', 'type' => 'integer', 'format' => 'int32' }, 'name' => { 'description' => '', 'type' => 'string' } } },
-      'UseResponse' => { 'type' => 'object', 'properties' => { 'description' => { 'description' => '', 'type' => 'string' }, 'items' => { 'type' => 'array', 'items' => { '$ref' => '#/definitions/ResponseItem' }, 'description' => '' } }, 'description' => 'This returns something' }
+      'UseResponse' => { 'type' => 'object', 'properties' => { 'description' => { 'description' => '', 'type' => 'string' }, '$responses' => { 'type' => 'array', 'items' => { '$ref' => '#/definitions/ResponseItem' }, 'description' => '' } }, 'description' => 'This returns something' }
     }
   end
 
@@ -279,7 +279,6 @@ RSpec.shared_context 'representable swagger example' do
       'paths' => {
         '/v3/other_thing/{elements}' => {
           'get' => {
-            'summary' => 'nested route inside namespace',
             'description' => 'nested route inside namespace',
             'produces' => ['application/json'],
             'parameters' => [{ 'in' => 'body', 'name' => 'elements', 'description' => 'Set of configuration', 'type' => 'array', 'items' => { 'type' => 'string' }, 'required' => true }],
@@ -292,7 +291,6 @@ RSpec.shared_context 'representable swagger example' do
         },
         '/thing' => {
           'get' => {
-            'summary' => 'This gets Things.',
             'description' => 'This gets Things.',
             'produces' => ['application/json'],
             'parameters' => [
@@ -306,7 +304,6 @@ RSpec.shared_context 'representable swagger example' do
             'operationId' => 'getThing'
           },
           'post' => {
-            'summary' => 'This creates Thing.',
             'description' => 'This creates Thing.',
             'produces' => ['application/json'],
             'consumes' => ['application/json'],
@@ -321,7 +318,6 @@ RSpec.shared_context 'representable swagger example' do
         },
         '/thing/{id}' => {
           'get' => {
-            'summary' => 'This gets Thing.',
             'description' => 'This gets Thing.',
             'produces' => ['application/json'],
             'parameters' => [{ 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }],
@@ -330,7 +326,6 @@ RSpec.shared_context 'representable swagger example' do
             'operationId' => 'getThingId'
           },
           'put' => {
-            'summary' => 'This updates Thing.',
             'description' => 'This updates Thing.',
             'produces' => ['application/json'],
             'consumes' => ['application/json'],
@@ -344,7 +339,6 @@ RSpec.shared_context 'representable swagger example' do
             'operationId' => 'putThingId'
           },
           'delete' => {
-            'summary' => 'This deletes Thing.',
             'description' => 'This deletes Thing.',
             'produces' => ['application/json'],
             'parameters' => [{ 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }],
@@ -355,7 +349,6 @@ RSpec.shared_context 'representable swagger example' do
         },
         '/thing2' => {
           'get' => {
-            'summary' => 'This gets Things.',
             'description' => 'This gets Things.',
             'produces' => ['application/json'],
             'responses' => { '200' => { 'description' => 'get Horses', 'schema' => { '$ref' => '#/definitions/Something' } }, '401' => { 'description' => 'HorsesOutError', 'schema' => { '$ref' => '#/definitions/ApiError' } } },
@@ -365,7 +358,6 @@ RSpec.shared_context 'representable swagger example' do
         },
         '/dummy/{id}' => {
           'delete' => {
-            'summary' => 'dummy route.',
             'description' => 'dummy route.',
             'produces' => ['application/json'],
             'parameters' => [{ 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }],

data/spec/swagger_v2/api_swagger_v2_mounted_spec.rb

@@ -106,8 +106,7 @@ describe 'swagger spec v2.0' do
         end
 
         version 'v3', using: :path
-        add_swagger_documentation hide_format: true,
-                                  base_path: '/api',
+        add_swagger_documentation base_path: '/api',
                                   info: {
                                     title: 'The API title to be displayed on the API homepage.',
                                     description: 'A description of the API.',

data/spec/swagger_v2/api_swagger_v2_response_spec.rb

@@ -47,7 +47,6 @@ describe 'response' do
     end
     specify do
       expect(subject['paths']['/nested_type']['get']).to eql(
-        'summary' => 'This returns something',
         'description' => 'This returns something',
         'produces' => ['application/json'],
         'responses' => {
@@ -69,7 +68,6 @@ describe 'response' do
 
     specify do
       expect(subject['paths']['/entity_response']['get']).to eql(
-        'summary' => 'This returns something',
         'description' => 'This returns something',
         'produces' => ['application/json'],
         'responses' => {
@@ -91,7 +89,6 @@ describe 'response' do
 
     specify do
       expect(subject['paths']['/params_given']['post']).to eql(
-        'summary' => 'This returns something',
         'description' => 'This returns something',
         'produces' => ['application/json'],
         'consumes' => ['application/json'],

data/spec/swagger_v2/api_swagger_v2_response_with_examples_spec.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'response with examples' do
+  include_context "#{MODEL_PARSER} swagger example"
+
+  before :all do
+    module TheApi
+      class ResponseApiExamples < Grape::API
+        format :json
+
+        desc 'This returns examples' do
+          success model: Entities::UseResponse, examples: { 'application/json' => { description: 'Names list', items: [{ id: '123', name: 'John' }] } }
+          failure [[404, 'NotFound', Entities::ApiError, { 'application/json' => { code: 404, message: 'Not found' } }]]
+        end
+        get '/response_examples' do
+          { 'declared_params' => declared(params) }
+        end
+
+        desc 'This syntax also returns examples' do
+          success model: Entities::UseResponse, examples: { 'application/json' => { description: 'Names list', items: [{ id: '123', name: 'John' }] } }
+          failure [
+            {
+              code: 404,
+              message: 'NotFound',
+              model: Entities::ApiError,
+              examples: { 'application/json' => { code: 404, message: 'Not found' } }
+            },
+            {
+              code: 400,
+              message: 'BadRequest',
+              model: Entities::ApiError,
+              examples: { 'application/json' => { code: 400, message: 'Bad Request' } }
+            }
+          ]
+        end
+        get '/response_failure_examples' do
+          { 'declared_params' => declared(params) }
+        end
+
+        desc 'This does not return examples' do
+          success model: Entities::UseResponse
+          failure [[404, 'NotFound', Entities::ApiError]]
+        end
+        get '/response_no_examples' do
+          { 'declared_params' => declared(params) }
+        end
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheApi::ResponseApiExamples
+  end
+
+  describe 'response examples' do
+    let(:example_200) do
+      { 'application/json' => { 'description' => 'Names list', 'items' => [{ 'id' => '123', 'name' => 'John' }] } }
+    end
+    let(:example_404) do
+      { 'application/json' => { 'code' => 404, 'message' => 'Not found' } }
+    end
+
+    subject do
+      get '/swagger_doc/response_examples'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/response_examples']['get']).to eql(
+        'description' => 'This returns examples',
+        'produces' => ['application/json'],
+        'responses' => {
+          '200' => { 'description' => 'This returns examples', 'schema' => { '$ref' => '#/definitions/UseResponse' }, 'examples' => example_200 },
+          '404' => { 'description' => 'NotFound', 'schema' => { '$ref' => '#/definitions/ApiError' }, 'examples' => example_404 }
+        },
+        'tags' => ['response_examples'],
+        'operationId' => 'getResponseExamples'
+      )
+    end
+  end
+
+  describe 'response failure examples' do
+    let(:example_200) do
+      { 'application/json' => { 'description' => 'Names list', 'items' => [{ 'id' => '123', 'name' => 'John' }] } }
+    end
+    let(:example_404) do
+      { 'application/json' => { 'code' => 404, 'message' => 'Not found' } }
+    end
+    let(:example_400) do
+      { 'application/json' => { 'code' => 400, 'message' => 'Bad Request' } }
+    end
+
+    subject do
+      get '/swagger_doc/response_failure_examples'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/response_failure_examples']['get']).to eql(
+        'description' => 'This syntax also returns examples',
+        'produces' => ['application/json'],
+        'responses' => {
+          '200' => { 'description' => 'This syntax also returns examples', 'schema' => { '$ref' => '#/definitions/UseResponse' }, 'examples' => example_200 },
+          '404' => { 'description' => 'NotFound', 'schema' => { '$ref' => '#/definitions/ApiError' }, 'examples' => example_404 },
+          '400' => { 'description' => 'BadRequest', 'schema' => { '$ref' => '#/definitions/ApiError' }, 'examples' => example_400 }
+        },
+        'tags' => ['response_failure_examples'],
+        'operationId' => 'getResponseFailureExamples'
+      )
+    end
+  end
+
+  describe 'response no examples' do
+    subject do
+      get '/swagger_doc/response_no_examples'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/response_no_examples']['get']).to eql(
+        'description' => 'This does not return examples',
+        'produces' => ['application/json'],
+        'responses' => {
+          '200' => { 'description' => 'This does not return examples', 'schema' => { '$ref' => '#/definitions/UseResponse' } },
+          '404' => { 'description' => 'NotFound', 'schema' => { '$ref' => '#/definitions/ApiError' } }
+        },
+        'tags' => ['response_no_examples'],
+        'operationId' => 'getResponseNoExamples'
+      )
+    end
+  end
+end

data/spec/swagger_v2/api_swagger_v2_status_codes_spec.rb

@@ -2,7 +2,7 @@
 
 require 'spec_helper'
 
-describe 'http status code behaivours' do
+describe 'http status code behaviours' do
   include_context "#{MODEL_PARSER} swagger example"
 
   subject do
@@ -10,7 +10,7 @@ describe 'http status code behaivours' do
     JSON.parse(last_response.body)
   end
 
-  context 'when non-default success codes are deifined' do
+  context 'when non-default success codes are defined' do
     let(:app) do
       Class.new(Grape::API) do
         desc 'Has explicit success http_codes defined' do
@@ -31,6 +31,26 @@ describe 'http status code behaivours' do
     end
   end
 
+  context 'when success and failures are defined' do
+    let(:app) do
+      Class.new(Grape::API) do
+        desc 'Has explicit success http_codes defined' do
+          success code: 202, model: Entities::UseResponse, message: 'a changed status code'
+          failure [[400, 'Bad Request']]
+        end
+
+        post '/accepting_endpoint' do
+          'We got the message!'
+        end
+        add_swagger_documentation
+      end
+    end
+
+    it 'only includes the defined http codes' do
+      expect(subject['paths']['/accepting_endpoint']['post']['responses'].keys.sort).to eq(%w[202 400].sort)
+    end
+  end
+
   context 'when no success codes defined' do
     let(:app) do
       Class.new(Grape::API) do

data/spec/swagger_v2/default_api_spec.rb

@@ -31,7 +31,6 @@ describe 'Default API' do
         'paths' => {
           '/something' => {
             'get' => {
-              'summary' => 'This gets something.',
               'description' => 'This gets something.',
               'produces' => ['application/json'],
               'tags' => ['something'],
@@ -78,7 +77,6 @@ describe 'Default API' do
                             'paths' => {
                               '/something' => {
                                 'get' => {
-                                  'summary' => 'This gets something.',
                                   'description' => 'This gets something.',
                                   'produces' => ['application/json'],
                                   'tags' => ['something'],

data/spec/swagger_v2/deprecated_field_spec.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'deprecated endpoint' do
+  def app
+    Class.new(Grape::API) do
+      desc 'Deprecated endpoint', deprecated: true
+      get '/foobar' do
+        { foo: 'bar' }
+      end
+
+      add_swagger_documentation
+    end
+  end
+
+  subject do
+    get '/swagger_doc.json'
+    JSON.parse(last_response.body)
+  end
+
+  it 'includes the deprecated field' do
+    expect(subject['paths']['/foobar']['get']['deprecated']).to eql(true)
+  end
+end

data/spec/swagger_v2/guarded_endpoint_spec.rb

@@ -83,7 +83,6 @@ describe 'a guarded api endpoint' do
         'paths' => {
           '/auth' => {
             'get' => {
-              'summary' => 'Show endpoint if authenticated',
               'description' => 'Show endpoint if authenticated',
               'produces' => ['application/json'],
               'tags' => ['auth'],

data/spec/swagger_v2/hide_api_spec.rb

@@ -52,7 +52,6 @@ describe 'a hide mounted api' do
       'paths' => {
         '/simple' => {
           'get' => {
-            'summary' => 'Show this endpoint',
             'description' => 'Show this endpoint',
             'produces' => ['application/json'],
             'tags' => ['simple'],
@@ -62,7 +61,6 @@ describe 'a hide mounted api' do
         },
         '/lazy' => {
           'get' => {
-            'summary' => 'Lazily show endpoint',
             'description' => 'Lazily show endpoint',
             'produces' => ['application/json'],
             'tags' => ['lazy'],
@@ -115,7 +113,6 @@ describe 'a hide mounted api with same namespace' do
       'paths' => {
         '/simple/show' => {
           'get' => {
-            'summary' => 'Show this endpoint',
             'description' => 'Show this endpoint',
             'produces' => ['application/json'],
             'operationId' => 'getSimpleShow',
@@ -137,7 +134,6 @@ describe 'a hide mounted api with same namespace' do
       'paths' => {
         '/simple/show' => {
           'get' => {
-            'summary' => 'Show this endpoint',
             'description' => 'Show this endpoint',
             'produces' => ['application/json'],
             'tags' => ['simple'],

data/spec/swagger_v2/mount_override_api_spec.rb

@@ -50,7 +50,6 @@ describe 'mount override api' do
     end
 
     it 'shows documentation from new endpoint' do
-      expect(subject['summary']).to eql('new endpoint')
       expect(subject['parameters'][0]['description']).to eql('new param')
       expect(subject['parameters'][0]['type']).to eql('string')
       expect(subject['responses']['200']['description']).to eql('new message')

data/spec/swagger_v2/mounted_target_class_spec.rb

@@ -39,7 +39,6 @@ describe 'docs mounted separately from api' do
       'paths' => {
         '/simple' => {
           'get' => {
-            'summary' => 'This gets something.',
             'description' => 'This gets something.',
             'produces' => ['application/json'],
             'responses' => { '200' => { 'description' => 'This gets something.' } },
@@ -62,7 +61,6 @@ describe 'docs mounted separately from api' do
       'paths' => {
         '/simple' => {
           'get' => {
-            'summary' => 'This gets something.',
             'description' => 'This gets something.',
             'produces' => ['application/json'],
             'responses' => {

data/spec/swagger_v2/simple_mounted_api_spec.rb

@@ -102,7 +102,6 @@ describe 'a simple mounted api' do
         'paths' => {
           '/' => {
             'get' => {
-              'summary' => 'Document root',
               'description' => 'Document root',
               'produces' => ['application/json'],
               'responses' => { '200' => { 'description' => 'Document root' } },
@@ -111,7 +110,6 @@ describe 'a simple mounted api' do
           },
           '/simple' => {
             'get' => {
-              'summary' => 'This gets something.',
               'description' => 'This gets something.',
               'produces' => ['application/json'],
               'tags' => ['simple'],
@@ -121,7 +119,6 @@ describe 'a simple mounted api' do
           },
           '/simple-test' => {
             'get' => {
-              'summary' => 'This gets something for URL using - separator.',
               'description' => 'This gets something for URL using - separator.',
               'produces' => ['application/json'],
               'tags' => ['simple-test'],
@@ -147,7 +144,6 @@ describe 'a simple mounted api' do
           },
           '/simple_with_headers' => {
             'get' => {
-              'summary' => 'this gets something else',
               'description' => 'this gets something else',
               'produces' => ['application/json'],
               'parameters' => [
@@ -165,7 +161,6 @@ describe 'a simple mounted api' do
           },
           '/items' => {
             'post' => {
-              'summary' => 'this takes an array of parameters',
               'description' => 'this takes an array of parameters',
               'produces' => ['application/json'],
               'consumes' => ['application/json'],
@@ -177,7 +172,6 @@ describe 'a simple mounted api' do
           },
           '/custom' => {
             'get' => {
-              'summary' => 'this uses a custom parameter',
               'description' => 'this uses a custom parameter',
               'produces' => ['application/json'],
               'parameters' => [{ 'in' => 'formData', 'name' => 'custom', 'description' => 'array of items', 'required' => false, 'type' => 'array', 'items' => { 'type' => 'CustomType' } }],
@@ -209,7 +203,6 @@ describe 'a simple mounted api' do
         'paths' => {
           '/simple' => {
             'get' => {
-              'summary' => 'This gets something.',
               'description' => 'This gets something.',
               'produces' => ['application/json'],
               'tags' => ['simple'],
@@ -241,7 +234,6 @@ describe 'a simple mounted api' do
           'paths' => {
             '/simple-test' => {
               'get' => {
-                'summary' => 'This gets something for URL using - separator.',
                 'description' => 'This gets something for URL using - separator.',
                 'produces' => ['application/json'],
                 'tags' => ['simple-test'],
@@ -264,7 +256,6 @@ describe 'a simple mounted api' do
         expect(subject['paths']).to eq(
           '/simple_with_headers' => {
             'get' => {
-              'summary' => 'this gets something else',
               'description' => 'this gets something else',
               'produces' => ['application/json'],
               'parameters' => [
@@ -294,7 +285,6 @@ describe 'a simple mounted api' do
         expect(subject['paths']).to eq(
           '/items' => {
             'post' => {
-              'summary' => 'this takes an array of parameters',
               'description' => 'this takes an array of parameters',
               'produces' => ['application/json'],
               'consumes' => ['application/json'],
@@ -318,7 +308,6 @@ describe 'a simple mounted api' do
         expect(subject['paths']).to eq(
           '/custom' => {
             'get' => {
-              'summary' => 'this uses a custom parameter',
               'description' => 'this uses a custom parameter',
               'produces' => ['application/json'],
               'parameters' => [{ 'in' => 'formData', 'name' => 'custom', 'description' => 'array of items', 'required' => false, 'type' => 'array', 'items' => { 'type' => 'CustomType' } }],

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: grape-swagger
 version: !ruby/object:Gem::Version
-  version: 0.28.0
+  version: 0.29.0
 platform: ruby
 authors:
 - Tim Vandecasteele
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-02-03 00:00:00.000000000 Z
+date: 2018-05-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grape
@@ -130,11 +130,13 @@ files:
 - spec/swagger_v2/api_swagger_v2_param_type_spec.rb
 - spec/swagger_v2/api_swagger_v2_request_params_fix_spec.rb
 - spec/swagger_v2/api_swagger_v2_response_spec.rb
+- spec/swagger_v2/api_swagger_v2_response_with_examples_spec.rb
 - spec/swagger_v2/api_swagger_v2_spec.rb
 - spec/swagger_v2/api_swagger_v2_status_codes_spec.rb
 - spec/swagger_v2/api_swagger_v2_type-format_spec.rb
 - spec/swagger_v2/boolean_params_spec.rb
 - spec/swagger_v2/default_api_spec.rb
+- spec/swagger_v2/deprecated_field_spec.rb
 - spec/swagger_v2/description_not_initialized.rb
 - spec/swagger_v2/endpoint_versioned_path_spec.rb
 - spec/swagger_v2/errors_spec.rb
@@ -183,7 +185,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.3
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: Add auto generated documentation to your Grape API that can be displayed
@@ -244,11 +246,13 @@ test_files:
 - spec/swagger_v2/api_swagger_v2_param_type_spec.rb
 - spec/swagger_v2/api_swagger_v2_request_params_fix_spec.rb
 - spec/swagger_v2/api_swagger_v2_response_spec.rb
+- spec/swagger_v2/api_swagger_v2_response_with_examples_spec.rb
 - spec/swagger_v2/api_swagger_v2_spec.rb
 - spec/swagger_v2/api_swagger_v2_status_codes_spec.rb
 - spec/swagger_v2/api_swagger_v2_type-format_spec.rb
 - spec/swagger_v2/boolean_params_spec.rb
 - spec/swagger_v2/default_api_spec.rb
+- spec/swagger_v2/deprecated_field_spec.rb
 - spec/swagger_v2/description_not_initialized.rb
 - spec/swagger_v2/endpoint_versioned_path_spec.rb
 - spec/swagger_v2/errors_spec.rb