grape-swagger 0.31.0 → 0.31.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb1e3a26202efe81153ad53197d67e8e3865ba34271a841d35e921eea5dc7a77
-  data.tar.gz: e0d34f81243e4d327d5268d100d0f654c5fbb0b63f95e47a50ba74e7ced602b2
+  metadata.gz: 5e20b96cce4f137604bc4133b23249fde90b242160469cd6ed347d2840bd5b74
+  data.tar.gz: 5e6d17f9875b63983b186d920dc28cdc4a957f13bc9f511a61991dbc7196ce50
 SHA512:
-  metadata.gz: 97396d5bcecae0c152c5c67c060da11373cd080cd126f2e443766790663355ffb358743beb2b2d309fa80399b1cb813053bb83ef8f89686e0d6c63f2f2b23919
-  data.tar.gz: 5afd698ad351518cb9d5cc73dfe45360e182263203bab5993c2766fa5ece2cd6bf61328b90223e1b4883444798d9ae769b6f3dc32f7b442303911286d66a1e34
+  metadata.gz: f2596bf6f153d0447fec637fc4c035fa2bc1d3806feebf2f71a9e6fcd9c950a40d7bbd02fa703ad11994a0b4969fb014a0342a4dc01a7c3224c6670d126ffb73
+  data.tar.gz: 39e5bfb7503ae7ea188231768db59fd89b8ef41494edb18ec8bf3e1cc458fda5fcf6db381663e06681e2b4b476e454147a4494232c316901a88caf2955ea7e92

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2017-12-13 08:44:09 +0100 using RuboCop version 0.52.0.
+# on 2018-09-28 22:03:50 -0400 using RuboCop version 0.59.2.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -13,26 +13,20 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'grape-swagger.gemspec'
 
-
 # Offense count: 30
 Metrics/AbcSize:
-  Max: 56
-
-# Offense count: 3
-# Configuration parameters: CountComments.
-Metrics/ClassLength:
-  Max: 248
+  Max: 57
 
 # Offense count: 10
 Metrics/CyclomaticComplexity:
   Max: 13
 
-# Offense count: 20
-# Configuration parameters: CountComments.
+# Offense count: 22
+# Configuration parameters: CountComments, ExcludedMethods.
 Metrics/MethodLength:
-  Max: 40
+  Max: 44
 
-# Offense count: 6
+# Offense count: 7
 Metrics/PerceivedComplexity:
   Max: 14
 
@@ -41,6 +35,6 @@ Style/ClassVars:
   Exclude:
     - 'lib/grape-swagger/doc_methods.rb'
 
-# Offense count: 20
+# Offense count: 21
 Style/Documentation:
   Enabled: false

data/CHANGELOG.md

@@ -1,12 +1,8 @@
-### Next
+### 0.31.1 (October 23, 2018)
 
 #### Features
 
-* Your contribution here.
-
-#### Fixes
-
-* Your contribution here.
+* [#710](https://github.com/ruby-grape/grape-swagger/issues/710): Re-implement `api_documentation` and `specific_api_documentation` options - [@dblock](https://github.com/dblock).
 
 ###  0.31.0 (August 22, 2018)
 
@@ -14,7 +10,6 @@
 
 * [#622](https://github.com/ruby-grape/grape-swagger/pull/622): Add support for 'brackets' collection format - [@korstiaan](https://github.com/korstiaan).
 * [#637](https://github.com/ruby-grape/grape-swagger/pull/637): Add an option to add braces to array params - [@adie](https://github.com/adie).
-
 * [#688](https://github.com/ruby-grape/grape-swagger/pull/688): Use deep merge for nested parameter definitions - [@jdmurphy](https://github.com/jdmurphy).
 * [#691](https://github.com/ruby-grape/grape-swagger/pull/691): Disregard order when parsing request params for arrays - [@jdmurphy](https://github.com/jdmurphy).
 * [#696](https://github.com/ruby-grape/grape-swagger/pull/696): Delegate required properties parsing to model parsers - [@Bugagazavr](https://github.com/Bugagazavr).

data/Gemfile

@@ -26,7 +26,7 @@ group :development, :test do
   gem 'rake'
   gem 'rdoc'
   gem 'rspec', '~> 3.0'
-  gem 'rubocop', '~> 0.58', require: false
+  gem 'rubocop', '~> 0.59', require: false
 end
 
 group :test do

data/README.md

@@ -1,7 +1,6 @@
 [![Gem Version](https://badge.fury.io/rb/grape-swagger.svg)](http://badge.fury.io/rb/grape-swagger)
 [![Build Status](https://travis-ci.org/ruby-grape/grape-swagger.svg?branch=master)](https://travis-ci.org/ruby-grape/grape-swagger)
 [![Coverage Status](https://coveralls.io/repos/github/ruby-grape/grape-swagger/badge.svg?branch=master)](https://coveralls.io/github/ruby-grape/grape-swagger?branch=master)
-[![Dependency Status](https://gemnasium.com/ruby-grape/grape-swagger.svg)](https://gemnasium.com/ruby-grape/grape-swagger)
 [![Code Climate](https://codeclimate.com/github/ruby-grape/grape-swagger.svg)](https://codeclimate.com/github/ruby-grape/grape-swagger)
 
 ##### Table of Contents
@@ -21,7 +20,7 @@
 * [Rake Tasks](#rake)
 
 
-## What is grape-swagger? <a name="what" />
+## What is grape-swagger? <a name="what"></a>
 
 The grape-swagger gem provides an autogenerated documentation for your [Grape](https://github.com/ruby-grape/grape) API. The generated documentation is Swagger-compliant, meaning it can easily be discovered in [Swagger UI](https://github.com/wordnik/swagger-ui). You should be able to point [the petstore demo](http://petstore.swagger.io/) to your API.
 
@@ -30,7 +29,7 @@ The grape-swagger gem provides an autogenerated documentation for your [Grape](h
 This screenshot is based on the [Hussars](https://github.com/LeFnord/hussars) sample app.
 
 
-## Related Projects <a name="related" />
+## Related Projects <a name="related"></a>
 
 * [Grape](https://github.com/ruby-grape/grape)
 * [Grape Swagger Entity](https://github.com/ruby-grape/grape-swagger-entity)
@@ -40,7 +39,7 @@ This screenshot is based on the [Hussars](https://github.com/LeFnord/hussars) sa
 
 
 
-## Compatibility <a name="version" />
+## Compatibility <a name="version"></a>
 
 The following versions of grape, grape-entity and grape-swagger can currently be used together.
 
@@ -53,14 +52,14 @@ grape-swagger | swagger spec | grape                   | grape-entity | represen
 0.27.0        |     2.0      | >= 0.16.2               | >= 0.5.0     | >= 2.4.1      |
 
 
-## Swagger-Spec <a name="swagger-spec" />
+## Swagger-Spec <a name="swagger-spec"></a>
 
 Grape-swagger generates documentation per [Swagger / OpenAPI Spec 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md).
 
 <!-- validating it with: http://bigstickcarpet.com/swagger-parser/www/index.html -->
 
 
-## Installation <a name="install" />
+## Installation <a name="install"></a>
 
 Add to your Gemfile:
 
@@ -74,9 +73,9 @@ Please see [UPGRADING](UPGRADING.md) when upgrading from a previous version.
 
 
 
-## Usage <a name="usage" />
+## Usage <a name="usage"></a>
 
-Mount all your different APIs (with ```Grape::API``` superclass) on a root node. In the root class definition, include ```add_swagger_documentation```, this sets up the system and registers the documentation on '/swagger_doc'. See [example/config.ru](example/config.ru) for a simple demo.
+Mount all your different APIs (with `Grape::API` superclass) on a root node. In the root class definition, include `add_swagger_documentation`, this sets up the system and registers the documentation on '/swagger_doc'. See [example/config.ru](example/config.ru) for a simple demo.
 
 
 ```ruby
@@ -97,7 +96,7 @@ To explore your API, either download [Swagger UI](https://github.com/wordnik/swa
 
 
 
-## Model Parsers <a name="model_parsers" />
+## Model Parsers <a name="model_parsers"></a>
 
 Since 0.21.0, `Grape::Entity` is not a part of grape-swagger, you need to add `grape-swagger-entity` manually to your Gemfile.
 Also added support for [representable](https://github.com/apotonick/representable) via `grape-swagger-representable`.
@@ -183,7 +182,7 @@ end
 
 
 
-## Configure <a name="configure" />
+## Configure <a name="configure"></a>
 
 * [host](#host)
 * [base_path](#base_path)
@@ -200,7 +199,9 @@ end
 * [tags](#tags)
 * [hide_documentation_path](#hide_documentation_path)
 * [info](#info)
-* [array_uses_braces](#array_uses_braces)
+* [array_use_braces](#array_use_braces)
+* [api_documentation](#api_documentation)
+* [specific_api_documentation](#specific_api_documentation)
 
 You can pass a hash with optional configuration settings to ```add_swagger_documentation```.
 The examples show the default value.
@@ -214,7 +215,7 @@ add_swagger_documentation \
 ```
 
 
-#### host: <a name="host" />
+#### host: <a name="host"></a>
 Sets explicit the `host`, default would be taken from `request`.
 ```ruby
 add_swagger_documentation \
@@ -222,7 +223,7 @@ add_swagger_documentation \
 ```
 
 
-#### base_path: <a name="base_path" />
+#### base_path: <a name="base_path"></a>
 Base path of the API that's being exposed, default would be taken from `request`.
 ```ruby
 add_swagger_documentation \
@@ -232,21 +233,22 @@ add_swagger_documentation \
 `host` and `base_path` are also accepting a `proc` or `lambda`
 
 
-#### mount_path: <a name="mount_path" />
+#### mount_path: <a name="mount_path"></a>
 The path where the API documentation is loaded, default is: `/swagger_doc`.
 ```ruby
 add_swagger_documentation \
    mount_path: '/swagger_doc'
 ```
 
-#### add_base_path:
+#### add_base_path: <a name="add_base_path"></a>
 Add `basePath` key to the documented path keys, default is: `false`.
 ```ruby
 add_swagger_documentation \
    add_base_path: true # only if base_path given
 ```
 
-#### add_version:
+#### add_version: <a name="add_version"></a>
+
 Add `version` key to the documented path keys, default is: `true`,
 here the version is the API version, specified by `grape` in [`path`](https://github.com/ruby-grape/grape/#path)
 
@@ -256,7 +258,8 @@ add_swagger_documentation \
 ```
 
 
-#### doc_version: <a name="doc_version" />
+#### doc_version: <a name="doc_version"></a>
+
 Specify the version of the documentation at [info section](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#info-object), default is: `'0.0.1'`
 ```ruby
 add_swagger_documentation \
@@ -264,7 +267,8 @@ add_swagger_documentation \
 ```
 
 
-#### endpoint_auth_wrapper: <a name="endpoint_auth_wrapper" />
+#### endpoint_auth_wrapper: <a name="endpoint_auth_wrapper"></a>
+
 Specify the middleware to use for securing endpoints.
 
 ```ruby
@@ -273,7 +277,7 @@ add_swagger_documentation \
 ```
 
 
-#### swagger_endpoint_guard: <a name="swagger_endpoint_guard" />
+#### swagger_endpoint_guard: <a name="swagger_endpoint_guard"></a>
 Specify the method and auth scopes, used by the middleware for securing endpoints.
 
 ```ruby
@@ -282,7 +286,7 @@ add_swagger_documentation \
 ```
 
 
-#### token_owner: <a name="token_owner" />
+#### token_owner: <a name="token_owner"></a>
 Specify the token_owner method, provided by the middleware, which is typically named 'resource_owner'.
 
 ```ruby
@@ -291,7 +295,7 @@ add_swagger_documentation \
 ```
 
 
-#### security_definitions: <a name="security_definitions" />
+#### security_definitions: <a name="security_definitions"></a>
 Specify the [Security Definitions Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#security-definitions-object)
 
 _NOTE: [Swagger-UI is supporting only implicit flow yet](https://github.com/swagger-api/swagger-ui/issues/2406#issuecomment-248651879)_
@@ -307,7 +311,8 @@ add_swagger_documentation \
   }
 ```
 
-#### security: <a name="security" />
+#### security: <a name="security"></a>
+
 Specify the [Security Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#securityRequirementObject)
 
 ```ruby
@@ -320,7 +325,7 @@ add_swagger_documentation \
 ```
 
 
-#### models: <a name="models" />
+#### models: <a name="models"></a>
 A list of entities to document. Combine with the [grape-entity](https://github.com/ruby-grape/grape-entity) gem.
 
 These would be added to the definitions section of the swagger file.
@@ -334,7 +339,8 @@ add_swagger_documentation \
 ```
 
 
-#### tags: <a name="tags" />
+#### tags: <a name="tags"></a>
+
 A list of tags to document.  By default tags are automatically generated
 for endpoints based on route names.
 
@@ -346,7 +352,8 @@ add_swagger_documentation \
 ```
 
 
-#### hide_documentation_path: (default: `true`) <a name="hide_documentation_path" />
+#### hide_documentation_path: (default: `true`) <a name="hide_documentation_path"></a>
+
 ```ruby
 add_swagger_documentation \
    hide_documentation_path: true
@@ -355,7 +362,8 @@ add_swagger_documentation \
 Don't show the `/swagger_doc` path in the generated swagger documentation.
 
 
-#### info: <a name="info" />
+#### info: <a name="info"></a>
+
 ```ruby
 add_swagger_documentation \
   info: {
@@ -372,7 +380,8 @@ add_swagger_documentation \
 
 A hash merged into the `info` key of the JSON documentation.
 
-#### array_uses_braces: <a name="array_uses_braces" />
+#### array_use_braces: <a name="array_use_braces"></a>
+
 ```ruby
 add_swagger_documentation \
   array_use_braces: true
@@ -383,25 +392,43 @@ params do
   optional :metadata, type: Array[String]
 end
 ```
- with `array_uses_braces: true`:
+ with `array_use_braces: true`:
 ```
 metadata[]: { "name": "Asset ID", "value": "12345" }
 metadata[]: { "name": "Asset Tag", "value": "654321"}
 ```
- with `array_uses_braces: false`:
+ with `array_use_braces: false`:
 ```
 metadata: {"name": "Asset ID", "value": "123456"}
 metadata: {"name": "Asset Tag", "value": "654321"}
 ```
 
-## Routes Configuration <a name="routes" />
+#### 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"></a>
 
 * [Swagger Header Parameters](#headers)
 * [Hiding an Endpoint](#hiding)
 * [Overriding Auto-Generated Nicknames](#overriding-auto-generated-nicknames)
 * [Specify endpoint details](#details)
 * [Overriding the route summary](#summary)
-* [Overriding the tags](#tags)
+* [Overriding the tags](#overriding_the_tags)
 * [Deprecating routes](#deprecating-routes)
 * [Overriding the name of the body parameter](#body-param)
 * [Defining an endpoint as an array](#array)
@@ -420,7 +447,7 @@ metadata: {"name": "Asset Tag", "value": "654321"}
 * [Response examples documentation](#response-examples)
 * [Response headers documentation](#response-headers)
 
-#### Swagger Header Parameters  <a name="headers" />
+#### Swagger Header Parameters  <a name="headers"></a>
 
 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.
 
@@ -440,7 +467,7 @@ desc "Return super-secret information", {
 ```
 
 
-#### Hiding an Endpoint <a name="hiding" />
+#### Hiding an Endpoint <a name="hiding"></a>
 
 You can hide an endpoint by adding ```hidden: true``` in the description of the endpoint:
 
@@ -469,16 +496,16 @@ desc 'Conditionally hide this endpoint', hidden: lambda { ENV['EXPERIMENTAL'] !=
 ```
 
 
-#### Overriding Auto-Generated Nicknames <a name="overriding-auto-generated-nicknames" />
+#### Overriding Auto-Generated Nicknames <a name="overriding-auto-generated-nicknames"></a>
 
-You can specify a swagger nickname to use instead of the auto generated name by adding `:nickname 'string'``` in the description of the endpoint.
+You can specify a swagger nickname to use instead of the auto generated name by adding `:nickname 'string'` in the description of the endpoint.
 
 ```ruby
 desc 'Get a full list of pets', nickname: 'getAllPets'
 ```
 
 
-#### Specify endpoint details <a name="details" />
+#### Specify endpoint details <a name="details"></a>
 
 To specify further details for an endpoint, use the `detail` option within a block passed to `desc`:
 
@@ -490,7 +517,7 @@ get '/kittens' do
 ```
 
 
-#### Overriding the route summary <a name="summary" />
+#### Overriding the route summary <a name="summary"></a>
 
 To override the summary, add `summary: '[string]'` after the description.
 
@@ -505,7 +532,7 @@ end
 ```
 
 
-#### Overriding the tags <a name="tags" />
+#### Overriding the tags <a name="overriding_the_tags"></a>
 
 Tags are used for logical grouping of operations by resources or any other qualifier. To override the
 tags array, add `tags: ['tag1', 'tag2']` after the description.
@@ -520,7 +547,7 @@ end
 ```
 
 
-#### Deprecating routes <a name="deprecating-routes" />
+#### Deprecating routes <a name="deprecating-routes"></a>
 
 To deprecate a route add `deprecated: true` after the description.
 
@@ -534,7 +561,7 @@ end
 ```
 
 
-#### Overriding the name of the body parameter  <a name="body-param" />
+#### Overriding the name of the body parameter <a name="body-param"></a>
 
 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
@@ -550,7 +577,7 @@ end
 ```
 
 
-#### Defining an endpoint as an array <a name="array" />
+#### Defining an endpoint as an array <a name="array"></a>
 
 You can define an endpoint as an array by adding `is_array` in the description:
 
@@ -559,7 +586,7 @@ desc 'Get a full list of pets', is_array: true
 ```
 
 
-#### Using an options hash <a name="options" />
+#### Using an options hash <a name="options"></a>
 
 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.
 Since the syntax differs you'll need to adjust it accordingly:
@@ -579,7 +606,7 @@ get '/kittens' do
 ```
 
 
-#### Overriding parameter type <a name="overriding-param-type" />
+#### Overriding parameter type <a name="overriding-param-type"></a>
 
 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.
 
@@ -593,7 +620,7 @@ end
 ```
 
 
-#### Overriding data type of the parameter <a name="overriding-type-of-param" />
+#### Overriding data type of the parameter <a name="overriding-type-of-param"></a>
 
 You can override type, using the documentation hash.
 
@@ -617,7 +644,7 @@ end
 ```
 
 
-#### Multiple types <a name="multiple-types" />
+#### Multiple types <a name="multiple-types"></a>
 
 By default when you set multiple types, the first type is selected as swagger type
 
@@ -640,7 +667,7 @@ end
 ```
 
 
-#### Array of data type <a name="array-type" />
+#### Array of data type <a name="array-type"></a>
 
 Array types are also supported.
 
@@ -666,7 +693,7 @@ end
 ```
 
 
-#### Collection format of arrays <a name="collection-format" />
+#### Collection format of arrays <a name="collection-format"></a>
 
 You can set the collection format of an array, using the documentation hash.
 
@@ -700,7 +727,7 @@ end
 ```
 
 
-#### Hiding parameters <a name="hiding-parameters" />
+#### Hiding parameters <a name="hiding-parameters"></a>
 
 Exclude single optional parameter from the documentation
 
@@ -715,7 +742,7 @@ end
 ```
 
 
-#### Setting a Swagger default value <a name="default-value" />
+#### Setting a Swagger default value <a name="default-value"></a>
 
 Grape allows for an additional documentation hash to be passed to a parameter.
 
@@ -785,7 +812,7 @@ end
 ```
 
 
-#### Response documentation <a name="response" />
+#### Response documentation <a name="response"></a>
 
 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.
 
@@ -794,7 +821,7 @@ In the following cases, the schema ref would be taken from route.
 ```ruby
 desc 'thing', failure: [ { code: 400, message: 'Invalid parameter entry' } ]
 get '/thing' do
-  ...
+  # ...
 end
 ```
 
@@ -804,7 +831,7 @@ desc 'thing' do
   failure [ { code: 400, message: 'Invalid parameter entry' } ]
 end
 get '/thing' do
-  ...
+  # ...
 end
 ```
 
@@ -813,7 +840,7 @@ get '/thing', failure: [
   { code: 400, message: 'Invalid parameter entry' },
   { code: 404, message: 'Not authorized' },
 ] do
-  ...
+  # ...
 end
 ```
 
@@ -823,7 +850,7 @@ get '/thing', failure: [
   { 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#L210) would be taken.
@@ -848,7 +875,7 @@ The result is then something like following:
 ```
 
 
-#### Changing default status codes <a name="change-status" />
+#### Changing default status codes <a name="change-status"></a>
 
 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.
 
@@ -859,7 +886,6 @@ get do
   status 202
   # your code comes here
 end
-…
 ```
 
 ```json
@@ -874,16 +900,16 @@ end
 ```
 
 
-#### File response <a name="file-response" />
+#### File response <a name="file-response"></a>
+
+Setting `success` to `File` sets a default `produces` of `application/octet-stream`.
 
-Set `success` to `File` and sets also produces. If produces wasn't set, it defaults to `application/octet-stream`.
 ```ruby
 desc 'Get a file',
     success: File
 get do
-  # your file reponse
+  # your file response
 end
-…
 ```
 
 ```json
@@ -901,10 +927,11 @@ end
 ```
 
 
-#### Extensions <a name="extensions" />
+#### Extensions <a name="extensions"></a>
 
 Swagger spec2.0 supports extensions on different levels, for the moment,
 the documentation on the root level object and the `info`, `verb`, `path` and `definition` levels are supported.
+
 The documented key would be generated from the `x` + `-` + key of the submitted hash,
 for possibilities refer to the [extensions spec](spec/lib/extensions_spec.rb).
 To get an overview *how* the extensions would be defined on grape level, see the following examples:
@@ -1004,7 +1031,7 @@ route_setting :x_def, [{ for: 422, other: 'stuff' }, { for: 200, some: 'stuff' }
 ```
 
 
-#### Response examples documentation <a name="response-examples" />
+#### Response examples documentation <a name="response-examples"></a>
 
 You can also add examples to your responses by using the `desc` DSL with block syntax.
 
@@ -1058,7 +1085,7 @@ The result will look like following:
 
 Failure information can be passed as an array of arrays or an array of hashes.
 
-#### Response headers documentation <a name="response-headers" />
+#### Response headers documentation <a name="response-headers"></a>
 
 You can also add header information to your responses by using the `desc` DSL with block syntax.
 
@@ -1113,7 +1140,7 @@ The result will look like following:
 
 Failure information can be passed as an array of arrays or an array of hashes.
 
-## Using Grape Entities <a name="grape-entity" />
+## Using Grape Entities <a name="grape-entity"></a>
 
 Add the [grape-entity](https://github.com/ruby-grape/grape-entity) and [grape-swagger-entity](https://github.com/ruby-grape/grape-swagger-entity) gem to your Gemfile.
 
@@ -1234,7 +1261,7 @@ end
 
 
 
-## Securing the Swagger UI <a name="oauth" />
+## Securing the Swagger UI <a name="oauth"></a>
 
 The Swagger UI on Grape could be secured from unauthorized access using any middleware, which provides certain methods:
 
@@ -1304,7 +1331,7 @@ role - only admins can see this endpoint.
 
 
 
-## Example <a name="example" />
+## Example <a name="example"></a>
 
 Go into example directory and run it: `$ bundle exec rackup`
 go to: `http://localhost:9292/swagger_doc` to get it
@@ -1349,7 +1376,7 @@ end
 
 
 
-## Rake Tasks <a name="rake" />
+## Rake Tasks <a name="rake"></a>
 
 Add these lines to your Rakefile, and initialize the Task class with your Api class – be sure your Api class is available.
 

data/RELEASING.md

@@ -1,6 +1,6 @@
 # Releasing Grape-Swagger
 
-There're no particular rules about when to release grape-swagger. Release bug fixes frequently, features not so frequently and breaking API changes rarely.
+There are no particular rules about when to release grape-swagger. Any co-maintainer is encouraged to release bug fixes frequently, features not so frequently and breaking API changes rarely.
 
 ### Release
 
@@ -13,18 +13,13 @@ rake
 
 Check that the last build succeeded in [Travis CI](https://travis-ci.org/ruby-grape/grape-swagger) for all supported platforms.
 
-Increment the version, modify [lib/grape-swagger/version.rb](lib/grape-swagger/version.rb).
-
-*  Increment the third number if the release has bug fixes and/or very minor features, only (eg. change `0.7.1` to `0.7.2`).
-*  Increment the second number if the release contains major features or breaking API changes (eg. change `0.7.1` to `0.8.0`).
-
-Change "Next Release" in [CHANGELOG.md](CHANGELOG.md) to the new version.
+Change "Next" in [CHANGELOG.md](CHANGELOG.md) to the current date.
 
 ```
 ### 0.7.2 (February 6, 2014)
 ```
 
-Remove the line with "Your contribution here.", since there will be no more contributions to this release.
+Remove the lines with "Your contribution here.", since there will be no more contributions to this release.
 
 Commit your changes.
 
@@ -47,11 +42,18 @@ Pushed grape-swagger 0.7.2 to rubygems.org.
 
 ### Prepare for the Next Version
 
+Increment the minor version, the third number, modify [lib/grape-swagger/version.rb](lib/grape-swagger/version.rb). For example, change `0.7.1` to `0.7.2`. Major versions are incremented in pull requests that require it.
+
 Add the next release to [CHANGELOG.md](CHANGELOG.md).
 
 ```
-Next Release
-============
+### 0.7.3 (Next)
+
+#### Features
+
+* Your contribution here.
+
+#### Fixes
 
 * Your contribution here.
 ```
@@ -59,8 +61,8 @@ Next Release
 Commit your changes.
 
 ```
-git add CHANGELOG.md
-git commit -m "Preparing for next release."
+git add CHANGELOG.md lib/grape-swagger/version.rb
+git commit -m "Preparing for next developer iteration, 0.7.3."
 git push origin master
 ```
 

data/lib/grape-swagger.rb

@@ -64,12 +64,15 @@ module Grape
           route_path = route.path
           route_match = route_path.split(/^.*?#{route.prefix.to_s}/).last
           next unless route_match
+
           route_match = route_match.match('\/([\w|-]*?)[\.\/\(]') || route_match.match('\/([\w|-]*)$')
           next unless route_match
+
           resource = route_match.captures.first
           resource = '/' if resource.empty?
           @target_class.combined_routes[resource] ||= []
           next if doc_klass.hide_documentation_path && route.path.match(/#{doc_klass.mount_path}($|\/|\(\.)/)
+
           @target_class.combined_routes[resource].unshift route
         end
       end
@@ -131,6 +134,7 @@ module Grape
       def extract_parent_route(name)
         route_name = name.match(%r{^/?([^/]*).*$})[1]
         return route_name unless route_name.include? ':'
+
         matches = name.match(/\/[a-z]+/)
         matches.nil? ? route_name : matches[0].delete('/')
       end

data/lib/grape-swagger/doc_methods.rb

@@ -32,6 +32,8 @@ module GrapeSwagger
       target_class     = options[:target_class]
       guard            = options[:swagger_endpoint_guard]
       formatter        = options[:format]
+      api_doc          = options[:api_documentation].dup
+      specific_api_doc = options[:specific_api_documentation].dup
 
       class_variables_from(options)
 
@@ -41,6 +43,8 @@ module GrapeSwagger
         end
       end
 
+      desc api_doc.delete(:desc), api_doc
+
       instance_eval(guard) unless guard.nil?
 
       output_path_definitions = proc do |combi_routes, endpoint|
@@ -67,10 +71,14 @@ module GrapeSwagger
         output_path_definitions.call(target_class.combined_namespace_routes, self)
       end
 
+      desc specific_api_doc.delete(:desc), { params:
+        specific_api_doc.delete(:params) || {} }.merge(specific_api_doc)
+
       params do
         requires :name, type: String, desc: 'Resource name of mounted API'
         optional :locale, type: Symbol, desc: 'Locale of API documentation'
       end
+
       get "#{mount_path}/:name" do
         I18n.locale = params[:locale] || I18n.default_locale
 

data/lib/grape-swagger/doc_methods/build_model_definition.rb

@@ -44,8 +44,8 @@ module GrapeSwagger
         end
 
         def deprecated_workflow_for(gem_name)
-          warn "DEPRECATED: You using old #{gem_name} version, wich not provides" \
-            "required attributes, to solve this problem please update #{gem_name}"
+          warn "DEPRECATED: You are using old #{gem_name} version, which doesn't provide " \
+            "required attributes. To solve this problem, please update #{gem_name}"
         end
       end
     end

data/lib/grape-swagger/doc_methods/extensions.rb

@@ -44,6 +44,7 @@ module GrapeSwagger
 
         def setup_definition(def_extension, path, definitions)
           return unless def_extension.key?(:for)
+
           status = def_extension[:for]
 
           definition = find_definition(status, path)
@@ -60,6 +61,7 @@ module GrapeSwagger
 
         def add_extension_to(part, extensions)
           return if part.nil?
+
           concatenate(extensions).each do |key, value|
             part[key] = value unless key.start_with?('x-for')
           end

data/lib/grape-swagger/doc_methods/move_params.rb

@@ -94,6 +94,7 @@ module GrapeSwagger
           property_keys.each_with_object({}) do |x, memo|
             value = param[x]
             next if value.blank?
+
             if x == :type && @definitions[value].present?
               memo['$ref'] = "#/definitions/#{value}"
             else
@@ -207,7 +208,7 @@ module GrapeSwagger
         end
 
         def property_keys
-          %i[type format description minimum maximum items enum]
+          %i[type format description minimum maximum items enum default]
         end
 
         def deletable?(param)

data/lib/grape-swagger/doc_methods/optional_object.rb

@@ -7,6 +7,7 @@ module GrapeSwagger
         def build(key, options, request = nil)
           if options[key]
             return evaluate(key, options, request) if options[key].is_a?(Proc)
+
             options[key]
           else
             request.send(default_values[key])

data/lib/grape-swagger/doc_methods/produces_consumes.rb

@@ -6,6 +6,7 @@ module GrapeSwagger
       class << self
         def call(*args)
           return ['application/json'] unless args.flatten.present?
+
           args.flatten.map { |x| Grape::ContentTypes::CONTENT_TYPES[x] || x }.uniq
         end
       end

data/lib/grape-swagger/endpoint.rb

@@ -172,6 +172,7 @@ module Grape
 
     def consumes_object(route, format)
       return unless SUPPORTS_CONSUMES.include?(route.request_method.downcase.to_sym)
+
       GrapeSwagger::DocMethods::ProducesConsumes.call(route.settings.dig(:description, :consumes) || format)
     end
 
@@ -321,6 +322,7 @@ module Grape
       model_name = model_name(model)
 
       return model_name if @definitions.key?(model_name)
+
       @definitions[model_name] = nil
 
       parser = GrapeSwagger.model_parsers.find(model)
@@ -345,6 +347,7 @@ module Grape
       route_hidden = route.settings.try(:[], :swagger).try(:[], :hidden)
       route_hidden = route.options[:hidden] if route.options.key?(:hidden)
       return route_hidden unless route_hidden.is_a?(Proc)
+
       options[:token_owner] ? route_hidden.call(send(options[:token_owner].to_sym)) : route_hidden.call
     end
   end

data/lib/grape-swagger/endpoint/params_parser.rb

@@ -51,8 +51,10 @@ module GrapeSwagger
       def param_type_is_array?(param_type)
         return false unless param_type
         return true if param_type == 'Array'
+
         param_types = param_type.match(/\[(.*)\]$/)
         return false unless param_types
+
         param_types = param_types[0].split(',') if param_types
         param_types.size == 1
       end
@@ -64,6 +66,7 @@ module GrapeSwagger
       def public_parameter?(param)
         param_options = param.last
         return true unless param_options.key?(:documentation) && !param_options[:required]
+
         param_hidden = param_options[:documentation].fetch(:hidden, false)
         param_hidden = param_hidden.call if param_hidden.is_a?(Proc)
         !param_hidden

data/lib/grape-swagger/version.rb

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

data/spec/swagger_v2/api_documentation_spec.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'API with additional options' do
+  let(:api) do
+    Class.new(Grape::API) do
+      add_swagger_documentation \
+        api_documentation: { desc: 'Swagger compatible API description' },
+        specific_api_documentation: { desc: 'Swagger compatible API description for specific API' }
+    end
+  end
+
+  subject do
+    api.routes.map do |route|
+      route.settings[:description]
+    end
+  end
+
+  it 'documents api' do
+    expect(subject).to eq(
+      [
+        { description: 'Swagger compatible API description' },
+        {
+          description: 'Swagger compatible API description for specific API',
+          params: {
+            'locale' => {
+              desc: 'Locale of API documentation',
+              required: false,
+              type: 'Symbol'
+            },
+            'name' => {
+              desc: 'Resource name of mounted API',
+              required: true,
+              type: 'String'
+            }
+          }
+        }
+      ]
+    )
+  end
+end

data/spec/swagger_v2/api_swagger_v2_format-content_type_spec.rb

@@ -41,7 +41,7 @@ describe 'format, content_type' do
           { 'declared_params' => declared(params) }
         end
 
-        desc 'This uses produces for produces',
+        desc 'This uses consumes for consumes',
              failure: [{ code: 400, model: Entities::ApiError }],
              consumes: ['application/www_url_encoded'],
              entity: Entities::UseResponse

data/spec/swagger_v2/guarded_endpoint_spec.rb

@@ -28,6 +28,7 @@ class SampleAuth < Grape::Middleware::Base
     context.protected_endpoint = context.options[:route_options][:auth].present?
 
     return unless context.protected_endpoint?
+
     scopes = context.options[:route_options][:auth][:scopes]
     authorize!(*scopes) unless scopes.include? false
     context.access_token = env['HTTP_AUTHORIZATION']

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: grape-swagger
 version: !ruby/object:Gem::Version
-  version: 0.31.0
+  version: 0.31.1
 platform: ruby
 authors:
 - Tim Vandecasteele
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-08-22 00:00:00.000000000 Z
+date: 2018-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grape
@@ -115,6 +115,7 @@ files:
 - spec/support/model_parsers/representable_parser.rb
 - spec/support/namespace_tags.rb
 - spec/support/the_paths_definitions.rb
+- spec/swagger_v2/api_documentation_spec.rb
 - spec/swagger_v2/api_swagger_v2_body_definitions_spec.rb
 - spec/swagger_v2/api_swagger_v2_definitions-models_spec.rb
 - spec/swagger_v2/api_swagger_v2_detail_spec.rb
@@ -148,7 +149,7 @@ files:
 - spec/swagger_v2/grape-swagger_spec.rb
 - spec/swagger_v2/guarded_endpoint_spec.rb
 - spec/swagger_v2/hide_api_spec.rb
-- spec/swagger_v2/host.rb
+- spec/swagger_v2/host_spec.rb
 - spec/swagger_v2/mount_override_api_spec.rb
 - spec/swagger_v2/mounted_target_class_spec.rb
 - spec/swagger_v2/namespace_tags_prefix_spec.rb
@@ -188,7 +189,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.7
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: Add auto generated documentation to your Grape API that can be displayed
@@ -234,6 +235,7 @@ test_files:
 - spec/support/model_parsers/representable_parser.rb
 - spec/support/namespace_tags.rb
 - spec/support/the_paths_definitions.rb
+- spec/swagger_v2/api_documentation_spec.rb
 - spec/swagger_v2/api_swagger_v2_body_definitions_spec.rb
 - spec/swagger_v2/api_swagger_v2_definitions-models_spec.rb
 - spec/swagger_v2/api_swagger_v2_detail_spec.rb
@@ -267,7 +269,7 @@ test_files:
 - spec/swagger_v2/grape-swagger_spec.rb
 - spec/swagger_v2/guarded_endpoint_spec.rb
 - spec/swagger_v2/hide_api_spec.rb
-- spec/swagger_v2/host.rb
+- spec/swagger_v2/host_spec.rb
 - spec/swagger_v2/mount_override_api_spec.rb
 - spec/swagger_v2/mounted_target_class_spec.rb
 - spec/swagger_v2/namespace_tags_prefix_spec.rb