grape-swagger 0.24.0 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 99ac4d378547c6998e6c712a83eb82d8277786fb
-  data.tar.gz: 9d18548301ad46bd474671a770c5e528ee7a4f3c
+  metadata.gz: 65693b18186fa5904b3f3012ac7a94cec5d90a44
+  data.tar.gz: d7e2b413a40e081cd155e76a554b1d7f3c532c9f
 SHA512:
-  metadata.gz: b609366f8b1e964dbffbc0a65593bca55d050ac46cac23896627fd0b2b49f9a2b4fc368022e20d3e2866d458322d083a13f1bc44d7cc36c4bff323d7082497ed
-  data.tar.gz: 6c6e93549bf4b7eebc659155dcb21ce5d999ef811ea1f8dbceb7c6104b35c3765d0ea6ef16fb706303f9dcd86c99811862fd939af471cbb1a5ff730c9c07aa50
+  metadata.gz: 2e998b82aba1e6252f6e63fe9dcc2ea53cb6b8aa4f384de774ed71cae5855158378e3e8ecdf920742ec2f5a196434f80c7798713d75d2b1a593e5aed7b6b8719
+  data.tar.gz: 3047cca817fd55c251717de9cf015dc26272f6da6996b67e317b2e058c18ff02fdd42bc5b1835da03500e8096cfc7da4ba1b813b012b5ee1e1993e18d413b502

data/.gitignore

@@ -5,6 +5,9 @@ doc
 # bundler
 .bundle
 
+#IDEA temp files
+.idea
+
 # jeweler generated
 pkg
 

data/.rubocop.yml

@@ -4,3 +4,7 @@ AllCops:
     - example/**/*
 
 inherit_from: .rubocop_todo.yml
+
+Metrics/LineLength:
+  Exclude:
+    - spec/**/*

data/.rubocop_todo.yml

@@ -1,30 +1,20 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2016-05-11 23:53:37 +0300 using RuboCop version 0.40.0.
+# on 2016-10-31 11:51:42 +0100 using RuboCop version 0.45.0.
 # 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
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 1
-Lint/AmbiguousOperator:
-  Exclude:
-    - 'spec/lib/move_params_spec.rb'
-
-# Offense count: 1
-Lint/UnreachableCode:
-  Exclude:
-    - 'example/config.ru'
-
-# Offense count: 1
-Lint/UselessAssignment:
-  Exclude:
-    - 'spec/lib/move_params_spec.rb'
-
 # Offense count: 27
 Metrics/AbcSize:
   Max: 56
 
+# Offense count: 1
+# Configuration parameters: CountComments.
+Metrics/BlockLength:
+  Max: 30
+
 # Offense count: 3
 # Configuration parameters: CountComments.
 Metrics/ClassLength:
@@ -32,38 +22,32 @@ Metrics/ClassLength:
 
 # Offense count: 10
 Metrics/CyclomaticComplexity:
-  Max: 16
+  Max: 15
 
-# Offense count: 719
-# Configuration parameters: AllowHeredoc, AllowURI, URISchemes.
+# Offense count: 803
+# Configuration parameters: AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives.
 # URISchemes: http, https
 Metrics/LineLength:
-  Max: 454
+  Max: 160
 
-# Offense count: 31
+# Offense count: 34
 # Configuration parameters: CountComments.
 Metrics/MethodLength:
   Max: 101
 
-# Offense count: 6
+# Offense count: 5
 Metrics/PerceivedComplexity:
-  Max: 17
+  Max: 16
 
-# Offense count: 4
+# Offense count: 3
 Style/ClassVars:
   Exclude:
-    - 'example/api/endpoints.rb'
     - 'lib/grape-swagger/doc_methods.rb'
 
-# Offense count: 27
+# Offense count: 23
 Style/Documentation:
   Enabled: false
 
-# Offense count: 1
-Style/DoubleNegation:
-  Exclude:
-    - 'example/api/endpoints.rb'
-
 # Offense count: 5
 # Configuration parameters: ExpectMatchingDefinition, Regex, IgnoreExecutableScripts.
 Style/FileName:
@@ -74,7 +58,20 @@ Style/FileName:
     - 'spec/swagger_v2/api_swagger_v2_type-format_spec.rb'
     - 'spec/swagger_v2/grape-swagger_spec.rb'
 
-# Offense count: 3
+# Offense count: 94
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+# SupportedStyles: when_needed, always
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+# Offense count: 1
+# Cop supports --auto-correct.
+Style/MultilineIfModifier:
+  Exclude:
+    - 'lib/grape-swagger/grape/route.rb'
+
+# Offense count: 4
 # Cop supports --auto-correct.
 # Configuration parameters: EnforcedStyle, SupportedStyles, AllowInnerSlashes.
 # SupportedStyles: slashes, percent_r, mixed

data/.travis.yml

@@ -19,6 +19,8 @@ matrix:
       env: GRAPE_VERSION=0.16.2
     - rvm: 2.3.1
       env: GRAPE_VERSION=0.17.0
+    - rvm: 2.3.1
+      env: GRAPE_VERSION=0.18.0
     - rvm: 2.3.1
       env: GRAPE_VERSION=HEAD
     - rvm: 2.3.0

data/CHANGELOG.md

@@ -8,6 +8,21 @@
 
 * Your contribution here.
 
+### 0.25.0 (October 31, 2016)
+
+#### Features
+
+* [#524](https://github.com/ruby-grape/grape-swagger/pull/524): Use route tags for global tag set - [@LeFnord](https://github.com/LeFnord).
+* [#523](https://github.com/ruby-grape/grape-swagger/pull/523): Allow specifying custom tags at the route level - [@jordanfbrown](https://github.com/jordanfbrown).
+* [#520](https://github.com/ruby-grape/grape-swagger/pull/520): Response model can have required attributes - [@WojciechKo](https://github.com/WojciechKo).
+* [#510](https://github.com/ruby-grape/grape-swagger/pull/510): Use 'token_owner' instead of 'oauth_token' on Swagger UI endpoint authorization. - [@texpert](https://github.com/texpert).
+
+#### Fixes
+
+* [#527](https://github.com/ruby-grape/grape-swagger/pull/527): Accepts string as entity - [@LeFnord](https://github.com/LeFnord).
+* [#515](https://github.com/ruby-grape/grape-swagger/pull/515): Removes limit on model names - [@LeFnord](https://github.com/LeFnord).
+* [#511](https://github.com/ruby-grape/grape-swagger/pull/511): Fix incorrect data type linking for request params of entity types - [@serggl](https://github.com/serggl).
+
 ### 0.24.0 (September 23, 2016)
 
 #### Features

data/Gemfile

@@ -2,7 +2,7 @@ source 'http://rubygems.org'
 
 gemspec
 
-case version = ENV['GRAPE_VERSION'] || '~> 0.17.0'
+case version = ENV['GRAPE_VERSION'] || '~> 0.18'
 when 'HEAD'
   gem 'grape', github: 'ruby-grape/grape'
 else

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2012-2014 Tim Vandecasteele and Contributors
+Copyright (c) 2012-2016 Tim Vandecasteele, ruby-grape and Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -14,10 +14,9 @@
 * [Model Parsers](#model_parsers)
 * [Configure](#configure)
 * [Routes Configuration](#routes)
+* [Using Grape Entities](#grape-entity)
 * [Securing the Swagger UI](#oauth)
 * [Markdown](#md_usage)
-* [Response documentation](#response)
-* [Extensions](#extensions)
 * [Example](#example)
 * [Rake Tasks](#rake)
 
@@ -28,7 +27,7 @@ The grape-swagger gem provides an autogenerated documentation for your [Grape](h
 
 ![Demo Screenshot](example/swagger-example.png)
 
-These screenshot is based on the [Hussars](https://github.com/LeFnord/hussars) sample app.
+This screenshot is based on the [Hussars](https://github.com/LeFnord/hussars) sample app.
 
 <a name="related" />
 ## Related Projects
@@ -157,7 +156,7 @@ GrapeSwagger.model_parsers.insert_before(GrapeSwagger::Representable::Parser, Gr
 GrapeSwagger.model_parsers.insert_after(GrapeSwagger::Roar::Parser, GrapeSwagger::Representable::Parser, Representable::Decorator)
 ```
 
-As we know, `Roar::Decorator` uses as superclass `Representable::Decorator`, this allow to avoid problem when Roar objects will be processed by `GrapeSwagger::Representable::Parser`, instead `GrapeSwagger::Roar::Parser`.
+As we know, `Roar::Decorator` uses `Representable::Decorator` as a superclass, this allows to avoid a problem when Roar objects are processed by `GrapeSwagger::Representable::Parser` instead of `GrapeSwagger::Roar::Parser`.
 
 
 ### CORS
@@ -181,7 +180,7 @@ before do
   header['Access-Control-Allow-Origin'] = '*'
   header['Access-Control-Request-Method'] = '*'
 end
-````
+```
 
 
 <a name="configure" />
@@ -196,7 +195,7 @@ end
 * [markdown](#markdown)
 * [endpoint_auth_wrapper](#endpoint_auth_wrapper)
 * [swagger_endpoint_guard](#swagger_endpoint_guard)
-* [oauth_token](#oauth_token)
+* [token_owner](#token_owner)
 * [security_definitions](#security_definitions)
 * [models](#models)
 * [hide_documentation_path](#hide_documentation_path)
@@ -204,10 +203,10 @@ end
 
 
 You can pass a hash with optional configuration settings to ```add_swagger_documentation```.
-The examples shows the default value.
+The examples show the default value.
 
 
-The `host` and `base_path` options also accept a `proc` or `lambda` to evaluate, which is passed a [request](http://www.rubydoc.info/github/rack/rack/Rack/Request) object:
+The `host` and `base_path` options also accept a `proc` or a `lambda` to evaluate, which is passed a [request](http://www.rubydoc.info/github/rack/rack/Rack/Request) object:
 
 ```ruby
 add_swagger_documentation \
@@ -296,19 +295,21 @@ add_swagger_documentation \
    swagger_endpoint_guard: 'oauth2 false'
 ```
 
-<a name="oauth_token" />
-#### oauth_token:
-Specify the method to get the oauth_token, provided by the middleware.
+<a name="token_owner" />
+#### token_owner:
+Specify the token_owner method, provided by the middleware, which is typically named 'resource_owner'.
 
 ```ruby
 add_swagger_documentation \
-   oauth_token: 'doorkeeper_access_token'
+   token_owner: 'resource_owner'
 ```
 
 <a name="security_definitions" />
 #### security_definitions:
 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)_
+
 ```ruby
 add_swagger_documentation \
   security_definitions: {
@@ -388,14 +389,20 @@ add_swagger_documentation \
 * [Swagger Header Parameters](#headers)
 * [Hiding an Endpoint](#hiding)
 * [Overriding Auto-Generated Nicknames](#overriding-auto-generated-nicknames)
-* [Defining an endpoint as array](#array)
-* [Using an options hash](#options)
 * [Specify endpoint details](#details)
-* [Overriding param type](#overriding-param-type)
-* [Overriding type](#overriding-type)
-* [Multi types](#multi-types)
+* [Overriding the route summary](#summary)
+* [Overriding the tags](#tags)
+* [Defining an endpoint as an array](#array)
+* [Using an options hash](#options)
+* [Overriding parameter type](#overriding-param-type)
+* [Overriding data type of the parameter](#overriding-type-of-param)
+* [Multiple types](#multiple-types)
+* [Array of data type](#array-type)
+* [Collection Format](#collection-format)
 * [Hiding parameters](#hiding-parameters)
+* [Setting a Swagger default value](#default-value)
 * [Response documentation](#response)
+* [Extensions](#extensions)
 
 
 <a name="headers" />
@@ -436,6 +443,7 @@ desc 'Conditionally hide this endpoint', hidden: lambda { ENV['EXPERIMENTAL'] !=
 ```
 
 
+<a name="overriding-auto-generated-nicknames" />
 #### 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.
@@ -445,10 +453,55 @@ desc 'Get a full list of pets', nickname: 'getAllPets'
 ```
 
 
+<a name="details" />
+#### Specify endpoint details
+
+To specify further details for an endpoint, use the `detail` option within a block passed to `desc`:
+
+```ruby
+desc 'Get all kittens!' do
+  detail 'this will expose all the kittens'
+end
+get '/kittens' do
+```
+
+
+<a name="summary" />
+#### Overriding the route summary
+
+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
+```
+
+
+<a name="tags" />
+#### Overriding the tags
+
+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.
+
+```ruby
+namespace 'order' do
+  desc 'This will be your summary', tags: ['orders']
+  get :order_id do
+    ...
+  end
+end
+```
+
+
 <a name="array" />
-#### Defining an endpoint as array
+#### Defining an endpoint as an array
 
-You can define an endpoint as array by adding `is_array` in the description:
+You can define an endpoint as an array by adding `is_array` in the description:
 
 ```ruby
 desc 'Get a full list of pets', is_array: true
@@ -466,8 +519,8 @@ desc 'Get all kittens!', {
   hidden: true,
   is_array: true,
   nickname: 'getKittens',
-  entity: Entities::Kitten, # or success
-  http_codes: [[401, 'KittenBitesError', Entities::BadKitten]] # or failure
+  success: Entities::Kitten, # or success
+  failures: [[401, 'KittenBitesError', Entities::BadKitten]] # or failure
   # also explicit as hash: [{ code: 401, mssage: 'KittenBitesError', model: Entities::BadKitten }]
   produces: [ "array", "of", "mime_types" ],
   consumes: [ "array", "of", "mime_types" ]
@@ -476,39 +529,54 @@ get '/kittens' do
 ```
 
 
-<a name="details" />
-#### Specify endpoint details
+<a name="overriding-param-type" />
+#### Overriding parameter type
 
-To specify further details for an endpoint, use the `detail` option within a block passed to `desc`:
+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.
 
 ```ruby
-desc 'Get all kittens!' do
-  detail 'this will expose all the kittens'
+params do
+  requires :action, type: Symbol, values: [:PAUSE, :RESUME, :STOP], documentation: { param_type: 'query' }
+end
+post :act do
+  ...
 end
-get '/kittens' do
 ```
 
 
-#### Overriding param type
+<a name="overriding-type-of-param" />
+#### Overriding data type of the parameter
 
-You can override paramType in POST|PUT methods to query, using the documentation hash.
+You can override type, using the documentation hash.
 
 ```ruby
 params do
-  requires :action, type: Symbol, values: [:PAUSE, :RESUME, :STOP], documentation: { param_type: 'query' }
+  requires :input, type: String, documentation: { type: 'integer' }
 end
 post :act do
   ...
 end
 ```
 
-#### Overriding type
+```json
+{
+  "in": "formData",
+  "name": "input",
+  "type": "integer",
+  "format": "int32",
+  "required": true
+}
+```
+
 
-You can override type, using the documentation hash.
+<a name="multiple-types" />
+#### Multiple types
+
+By default when you set multiple types, the first type is selected as swagger type
 
 ```ruby
 params do
-  requires :input, type: String, documentation: { type: 'integer' }
+  requires :action, types: [String, Integer]
 end
 post :act do
   ...
@@ -518,14 +586,15 @@ end
 ```json
 {
   "in": "formData",
-  "name": "input",
-  "type": "integer",
-  "format": "int32",
+  "name": "action",
+  "type": "string",
   "required": true
 }
 ```
 
-#### Array type
+
+<a name="array-type" />
+#### Array of data type
 
 Array types are also supported.
 
@@ -550,6 +619,8 @@ end
 }
 ```
 
+
+<a name="collection-format" />
 #### Collection format of arrays
 
 You can set the collection format of an array, using the documentation hash.
@@ -583,28 +654,8 @@ end
 }
 ```
 
-#### Multi types
-
-By default when you set multi types, the first type is selected as swagger type
-
-```ruby
-params do
-  requires :action, types: [String, Integer]
-end
-post :act do
-  ...
-end
-```
-
-```json
-{
-  "in": "formData",
-  "name": "action",
-  "type": "string",
-  "required": true
-}
-```
 
+<a name="hiding-parameters" />
 #### Hiding parameters
 
 Exclude single optional parameter from the documentation
@@ -619,28 +670,27 @@ post :act do
 end
 ```
 
-#### Overriding the route summary
 
-By default, the route summary is filled with the value supplied to `desc`.
+<a name="default-value" />
+#### Setting a Swagger default value
+
+Grape allows for an additional documentation hash to be passed to a parameter.
 
 ```ruby
-namespace 'order' do
-  desc 'This will be your summary'
-  get :order_id do
-    ...
-  end
+params do
+  requires :id, type: Integer, desc: 'Coffee ID'
+  requires :temperature, type: Integer, desc: 'Temperature of the coffee in celcius', documentation: { default: 72 }
 end
 ```
 
-To override the summary, add `summary: '[string]'` after the description.
+The example parameter will populate the Swagger UI with the example value, and can be used for optional or required parameters.
+
+Grape uses the option `default` to set a default value for optional parameters. This is different in that Grape will set your parameter to the provided default if the parameter is omitted, whereas the example value above will only set the value in the UI itself. This will set the Swagger `defaultValue` to the provided value. Note that the example value will override the Grape default value.
 
 ```ruby
-namespace 'order' do
-  desc 'This will be your summary',
-    summary: 'Now this is your summary!'
-  get :order_id do
-    ...
-  end
+params do
+  requires :id, type: Integer, desc: 'Coffee ID'
+  optional :temperature, type: Integer, desc: 'Temperature of the coffee in celcius', default: 72
 end
 ```
 
@@ -692,46 +742,140 @@ end
 ```
 
 
-<a name="additions" />
-## Additional documentation
-
-* [Markdown in Detail](#md_usage)
-* [Response documentation](#response)
+<a name="response" />
+#### Response documentation
 
-### Setting a Swagger defaultValue
+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.
 
-Grape allows for an additional documentation hash to be passed to a parameter.
+In the following cases, the schema ref would be taken from route.
 
 ```ruby
-params do
-  requires :id, type: Integer, desc: 'Coffee ID'
-  requires :temperature, type: Integer, desc: 'Temperature of the coffee in celcius', documentation: { default: 72 }
+desc 'thing', failures: [ { code: 400, message: "Invalid parameter entry" } ]
+get '/thing' do
+  ...
 end
 ```
 
-The example parameter will populate the Swagger UI with the example value, and can be used for optional or required parameters.
+```ruby
+desc 'thing' do
+  params Entities::Something.documentation
+  failures [ { code: 400, message: "Invalid parameter entry" } ]
+end
+get '/thing' do
+  ...
+end
+```
 
-Grape uses the option `default` to set a default value for optional parameters. This is different in that Grape will set your parameter to the provided default if the parameter is omitted, whereas the example value above will only set the value in the UI itself. This will set the Swagger `defaultValue` to the provided value. Note that the example value will override the Grape default value.
+```ruby
+get '/thing', failures: [
+  { code: 200, message: 'Ok' },
+  { code: 400, message: "Invalid parameter entry" }
+] do
+  ...
+end
+```
 
+By adding a `model` key, e.g. this would be taken.
 ```ruby
-params do
-  requires :id, type: Integer, desc: 'Coffee ID'
-  optional :temperature, type: Integer, desc: 'Temperature of the coffee in celcius', default: 72
+get '/thing', failures: [
+  { code: 200, message: 'Ok' },
+  { code: 422, message: "Invalid parameter entry", model: Entities::ApiError }
+] do
+  ...
 end
 ```
+If no status code is defined [defaults](/lib/grape-swagger/endpoint.rb#L121) would be taken.
+
+The result is then something like following:
+
+```json
+"responses": {
+  "200": {
+    "description": "get Horses",
+    "schema": {
+      "$ref": "#/definitions/Thing"
+    }
+  },
+  "401": {
+    "description": "HorsesOutError",
+    "schema": {
+      "$ref": "#/definitions/ApiError"
+    }
+  }
+},
+```
 
+<a name="extensions" />
+#### Extensions
 
-### Grape Entities
+Swagger spec2.0 supports extensions on different levels, for the moment,
+the documentation on `verb`, `path` and `definition` level would be 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:
 
-Add the [grape-entity](https://github.com/agileanimal/grape-entity) gem to your Gemfile.
+- `verb` extension, add a `x` key to the `desc` hash:
+```ruby
+desc 'This returns something with extension on verb level',
+  x: { some: 'stuff' }
+```
+this would generate:
+```json
+"/path":{
+  "get":{
+    "…":"…",
+    "x-some":"stuff"
+  }
+}
+```
 
-The following example exposes statuses. And exposes statuses documentation adding :type and :desc.
+- `path` extension, by setting via route settings:
+```ruby
+route_setting :x_path, { some: 'stuff' }
+```
+this would generate:
+```json
+"/path":{
+  "x-some":"stuff",
+  "get":{
+    "…":"…",
+  }
+}
+```
+
+- `definition` extension, again by setting via route settings,
+here the status code must be provided, for which definition the extensions should be:
+```ruby
+route_setting :x_def, { for: 422, other: 'stuff' }
+```
+this would generate:
+```json
+"/definitions":{
+  "ApiError":{
+    "x-other":"stuff",
+    "…":"…",
+  }
+}
+```
+or, for more definitions:
+```ruby
+route_setting :x_def, [{ for: 422, other: 'stuff' }, { for: 200, some: 'stuff' }]
+```
+
+
+<a name="grape-entity" />
+## Using Grape Entities
+
+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.
+
+The following example exposes statuses. And exposes statuses documentation adding :type, :desc and :required.
+The documented class/definition name could be set via `#entity_name`.
 
 ```ruby
 module API
   module Entities
     class Status < Grape::Entity
-      expose :text, documentation: { type: 'string', desc: 'Status update text.' }
+      expose :text, documentation: { type: 'string', desc: 'Status update text.', required: true }
       expose :links, using: Link, documentation: { type: 'link', is_array: true }
       expose :numbers, documentation: { type: 'integer', desc: 'favourite number', values: [1,2,3,4] }
     end
@@ -739,6 +883,11 @@ module API
     class Link < Grape::Entity
       expose :href, documentation: { type: 'url' }
       expose :rel, documentation: { type: 'string'}
+
+      def self.entity_name
+        'LinkedStatus'
+      end
+
     end
   end
 
@@ -764,12 +913,12 @@ end
 ```
 
 
-#### Relationships
+### Relationships
 
 You may safely omit `type` from relationships, as it can be inferred. However, if you need to specify or override it, use the full name of the class leaving out any modules named `Entities` or `Entity`.
 
 
-##### 1xN
+#### 1xN
 
 ```ruby
 module API
@@ -799,7 +948,7 @@ end
 ```
 
 
-##### 1x1
+#### 1x1
 
 Note: `is_array` is `false` by default.
 
@@ -836,9 +985,10 @@ end
 
 The Swagger UI on Grape could be secured from unauthorized access using any middleware, which provides certain methods:
 
-- a *before* method to be run in the Grape controller for authorization purpose;
 - some guard method, which could receive as argument a string or an array of authorization scopes;
-- a method which processes and returns the access token received in the HTTP request headers (usually in the 'HTTP_AUTHORIZATION' header).
+- a *before* method to be run in the Grape controller for authorization purpose;
+- a set of methods which will process the access token received in the HTTP request headers (usually in the
+'HTTP_AUTHORIZATION' header) and try to return the owner of the token.
 
 Below are some examples of securing the Swagger UI on Grape installed along with Ruby on Rails:
 
@@ -856,14 +1006,14 @@ This is how to configure the grape_swagger documentation:
                             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
-                            oauth_token: 'doorkeeper_access_token'      # This is the method returning the access_token
+                            token_owner: 'resource_owner'               # This is the method returning the owner of the token
 ```
 
 The guard method should inject the Security Requirement Object into the endpoint's route settings (see Grape::DSL::Settings.route_setting method).
 
-The 'oauth2 false' added to swagger_documentation is making the main Swagger endpoint protected with OAuth, i.e. it
-is retreiving the access_token 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
+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.  
 
 Further on, the guard could be used, where necessary, for endpoint access protection. Put it prior to the endpoint's method:
@@ -886,7 +1036,7 @@ And, finally, if you want to not only restrict the access, but to completely hid
 users, you could pass a lambda to the :hidden key of a endpoint's description:
 
 ```ruby
-  not_admins = lambda { |token=nil| token.nil? || !User.find(token.resource_owner_id).admin? }
+  not_admins = lambda { |token_owner = nil| token_owner.nil? || !token_owner.admin? }
 
   resource :users do
     desc 'Create user', hidden: not_admins
@@ -897,7 +1047,7 @@ users, you could pass a lambda to the :hidden key of a endpoint's description:
   end
 ```
 
-The lambda is checking whether the user is authenticated (if not, the token is nil by default), and has the admin
+The lambda is checking whether the user is authenticated (if not, the token_owner is nil by default), and has the admin
 role - only admins can see this endpoint.
 
 <a name="md_usage" />
@@ -974,126 +1124,6 @@ end
 ```
 
 
-<a name="response" />
-## Response documentation
-
-You can also document the HTTP status codes with a description and a specified model, as ref in the schema to the definitions, that your API returns with one of the following syntax.
-
-In the following cases, the schema ref would be taken from route.
-
-```ruby
-desc 'thing', http_codes: [ { code: 400, message: "Invalid parameter entry" } ]
-get '/thing' do
-  ...
-end
-```
-
-```ruby
-desc 'thing' do
-  params Entities::Something.documentation
-  http_codes [ { code: 400, message: "Invalid parameter entry" } ]
-end
-get '/thing' do
-  ...
-end
-```
-
-```ruby
-get '/thing', http_codes: [
-  { code: 200, message: 'Ok' },
-  { code: 400, message: "Invalid parameter entry" }
-] do
-  ...
-end
-```
-
-By adding a `model` key, e.g. this would be taken.
-```ruby
-get '/thing', http_codes: [
-  { code: 200, message: 'Ok' },
-  { code: 422, message: "Invalid parameter entry", model: Entities::ApiError }
-] do
-  ...
-end
-```
-If no status code is defined [defaults](/lib/grape-swagger/endpoint.rb#L121) would be taken.
-
-The result is then something like following:
-
-```json
-"responses": {
-  "200": {
-    "description": "get Horses",
-    "schema": {
-      "$ref": "#/definitions/Thing"
-    }
-  },
-  "401": {
-    "description": "HorsesOutError",
-    "schema": {
-      "$ref": "#/definitions/ApiError"
-    }
-  }
-},
-```
-
-<a name="extensions" />
-## Extensions
-
-Swagger spec2.0 supports extensions on different levels, for the moment,
-the documentation on `verb`, `path` and `definition` level would be 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:
-
-- `verb` extension, add a `x` key to the `desc` hash:
-```ruby
-desc 'This returns something with extension on verb level',
-  x: { some: 'stuff' }
-```
-this would generate:
-```json
-"/path":{
-  "get":{
-    "…":"…",
-    "x-some":"stuff"
-  }
-}
-```
-
-- `path` extension, by setting via route settings:
-```ruby
-route_setting :x_path, { some: 'stuff' }
-```
-this would generate:
-```json
-"/path":{
-  "x-some":"stuff",
-  "get":{
-    "…":"…",
-  }
-}
-```
-
-- `definition` extension, again by setting via route settings,
-here the status code must be provided, for which definition the extensions should be:
-```ruby
-route_setting :x_def, { for: 422, other: 'stuff' }
-```
-this would generate:
-```json
-"/definitions":{
-  "ApiError":{
-    "x-other":"stuff",
-    "…":"…",
-  }
-}
-```
-or, for more definitions:
-```ruby
-route_setting :x_def, [{ for: 422, other: 'stuff' }, { for: 200, some: 'stuff' }]
-```
-
 <a="example" />
 ## Example
 
@@ -1178,4 +1208,4 @@ See [CONTRIBUTING](CONTRIBUTING.md).
 
 ## Copyright and License
 
-Copyright (c) 2012-2014 Tim Vandecasteele and contributors. See [LICENSE.txt](LICENSE.txt) for details.
+Copyright (c) 2012-2016 Tim Vandecasteele, ruby-grape and contributors. See [LICENSE.txt](LICENSE.txt) for details.