grape-swagger 0.11.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d4e52b2b16e5431c3ef42aa544c85b084c003cf9
-  data.tar.gz: 86d13f947c54e91c207d58fda741b47f3cddd231
+  metadata.gz: 881259fe2427869fbd1dbe2af3925eff5c6ec991
+  data.tar.gz: 6557a2cee402f5f5fd8f4d03ca07b4abcb423531
 SHA512:
-  metadata.gz: f96ee66b108a5880309103e38fc2137bdbb3e993c679c192d943fdec6a467a57008babc39c4379c2a9f6c77e5da93d80f8c98b0996a35d09d4117a1355b13d37
-  data.tar.gz: 6041bc57d9612d87ccc5acf9c38089703835b3fa3f5a78233e63fec91866e5a82973da24c22cd78cf0b77758116562c5f3f7258cb48e0b0d23e5ea54d308ff46
+  metadata.gz: ecc8ed62a66df220e26243a208270fedbf80b91af6b5b26a8d5bb4f99486cdfd14cdd721929c0340dabffa739d49142b27102d89ef9081c0ff1ac5098bc616a6
+  data.tar.gz: 4bbf258316ad6e4ee1a56b5016e86150f29a63eb71047a943975979c60330b86e5f17e9e3554afc76f676d5a72b0af363efc09e25324113bb0d7b06c9cb656fc

data/.gitignore

@@ -30,4 +30,11 @@ Gemfile.lock
 # For MacOS:
 #
 .DS_Store
-.project
+.project
+example.json
+swagger_spec1.2/
+ToDo.md
+.ruby-version
+spec/params_entity_spec.rb
+vendor/bundle/
+spec/swagger_v2/x-dummy.rb

data/.rubocop.yml

@@ -1,5 +1,8 @@
 AllCops:
   Exclude:
     - vendor/**/*
+    - spec/**/*
+    - swagger_spec1.2/**/*
+    - example/**/*
 
 inherit_from: .rubocop_todo.yml

data/.rubocop_todo.yml

@@ -1,42 +1,42 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2016-04-09 20:38:17 -0400 using RuboCop version 0.33.0.
+# on 2015-08-19 12:17:53 -0400 using RuboCop version 0.33.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: 14
+# Offense count: 10
 Metrics/AbcSize:
-  Max: 222
+  Max: 176
 
 # Offense count: 1
 # Configuration parameters: CountComments.
 Metrics/ClassLength:
-  Max: 149
+  Max: 250
 
-# Offense count: 7
+# Offense count: 6
 Metrics/CyclomaticComplexity:
-  Max: 42
+  Max: 38
 
-# Offense count: 359
+# Offense count: 304
 # Configuration parameters: AllowURI, URISchemes.
 Metrics/LineLength:
-  Max: 206
+  Max: 242
 
-# Offense count: 24
+# Offense count: 21
 # Configuration parameters: CountComments.
 Metrics/MethodLength:
-  Max: 175
+  Max: 139
 
 # Offense count: 1
 # Configuration parameters: CountComments.
 Metrics/ModuleLength:
-  Max: 478
+  Max: 200
 
-# Offense count: 5
+# Offense count: 4
 Metrics/PerceivedComplexity:
-  Max: 44
+  Max: 38
 
 # Offense count: 8
 Style/ClassVars:
@@ -44,14 +44,13 @@ Style/ClassVars:
     - 'example/api.rb'
     - 'lib/grape-swagger/doc_methods.rb'
 
-# Offense count: 96
+# Offense count: 90
 Style/Documentation:
   Enabled: false
 
 # Offense count: 2
 Style/DoubleNegation:
   Exclude:
-    - 'lib/grape-swagger/doc_methods.rb'
 
 # Offense count: 3
 # Configuration parameters: Exclude.
@@ -61,16 +60,10 @@ Style/FileName:
     - 'spec/grape-swagger_helper_spec.rb'
     - 'spec/grape-swagger_spec.rb'
 
-# Offense count: 1
-Style/MultilineBlockChain:
-  Exclude:
-    - 'lib/grape-swagger/doc_methods.rb'
-
 # Offense count: 1
 # Configuration parameters: NamePrefix, NamePrefixBlacklist.
 Style/PredicateName:
   Exclude:
-    - 'lib/grape-swagger/doc_methods.rb'
 
 # Offense count: 4
 # Cop supports --auto-correct.
@@ -78,4 +71,3 @@ Style/PredicateName:
 Style/RegexpLiteral:
   Exclude:
     - 'lib/grape-swagger.rb'
-    - 'lib/grape-swagger/doc_methods.rb'

data/.travis.yml

@@ -3,16 +3,19 @@ language: ruby
 sudo: false
 
 rvm:
+  - 2.3.0
   - 2.2.3
   - 2.1.7
   - jruby-19mode
   - jruby-9.0.5.0
   - rbx-2
 
-env:
-  - GRAPE_VERSION=0.16.2
-  - GRAPE_VERSION=HEAD
-
 matrix:
   allow_failures:
     - rvm: rbx-2
+    - rvm: jruby-19mode
+env:
+  - GRAPE_VERSION=0.12.0
+  - GRAPE_VERSION=0.13.0
+  - GRAPE_VERSION=0.14.0
+  # - GRAPE_VERSION=HEAD

data/CHANGELOG.md

@@ -1,28 +1,55 @@
-### 0.11.0 (Next)
+### 0.20.0 / 2016-04-09
 
 #### Features
 
-* [#368](https://github.com/ruby-grape/grape-swagger/pull/368): Requires Grape 0.16.2, fixes `route_xxx` deprecation messages - [@dblock](https://github.com/dblock).
+[#371](https://github.com/ruby-grape/grape-swagger/pull/371)
 
-### 0.10.5 (2016-04-12)
+  - adds param type `body` handling
 
-* [#338](https://github.com/ruby-grape/grape-swagger/pull/338): Fixed handling of nested Array parameters - [@itoufo](https://github.com/itoufo).
-* [#347](https://github.com/ruby-grape/grape-swagger/pull/347): Fixed typeref when both :using and :as are provided in exposure but no :type in documentation - [@c910335](https://github.com/c910335).
+[#367](https://github.com/ruby-grape/grape-swagger/pull/367)
 
-#### Fixes
+  - set default `type: Integer` and `required: true` for path params,
+    if they wasn't specified inside the `params` bloack as required
+
+[#365](https://github.com/ruby-grape/grape-swagger/pull/365)
+
+- fixes passing markdown with redcarpet even with nil description and detail
+
+[#358](https://github.com/ruby-grape/grape-swagger/pull/358)
+
+- removes `allowMultiple` property from params
+- adds `format` to definition property
+- renames `defaultValue` to `default`
+
+
+[#356](https://github.com/ruby-grape/grape-swagger/pull/356)
+
+- adds `consumes` setting
+- refactoring
+
+[#354](https://github.com/ruby-grape/grape-swagger/pull/354) some improvements
+
+- fixes setting of `base_path` and `host`;
+- adds possibility to configure the setting of `version` and `base_path` in documented path;
+- adds `operationId`
+
+[#353](https://github.com/ruby-grape/grape-swagger/pull/353) resolves issue #352
+
+### 0.10.4 (Next)
 
-* [#322](https://github.com/ruby-grape/grape-swagger/pull/322): Entity's `entity_name` takes predence over root  - [@gekola](https://github.com/gekola).
-* [#321](https://github.com/ruby-grape/grape-swagger/pull/321): Fixed handling paths containing uppercase letters - [@gekola](https://github.com/gekola).
+[#344](https://github.com/ruby-grape/grape-swagger/pull/) Namespace based tag include in Swagger Json
 
-### 0.10.4 (December 7, 2015)
+* Namespace based tagging help the swagger GUI to group the API list
 
-* [#315](https://github.com/ruby-grape/grape-swagger/pull/315): Require `grape-entity` < 0.5.0 - [@dblock](https://github.com/dblock).
+### 0.10.3 (Next)
 
-### 0.10.3 (December 7, 2015)
+[#336](https://github.com/ruby-grape/grape-swagger/pull/336) changes of swagger-2.0 fork, to support it
 
-* [#292](https://github.com/ruby-grape/grape-swagger/pull/292): Support i18n - [@calfzhou](https://github.com/calfzhou).
-* [#297](https://github.com/ruby-grape/grape-swagger/pull/297): Correct use of documentation param_type - [@fab-girard](https://github.com/fab-girard).
-* [#305](https://github.com/ruby-grape/grape-swagger/pull/305): Speedup by parsing models smarter, not harder - [@jhollinger](https://github.com/jhollinger).
+* updates gems, corrects parameter, which is in array, make rubocop happy
+* runs under 2.3
+* documents produces of an end-point
+* Update api_swagger_v2_format-content_type_spec.rb
+* upgrades to grape 0.14.x; grape-entity 0.5.x
 
 ### 0.10.2 (August 19, 2015)
 
@@ -136,13 +163,13 @@
 
 * Added Rails 4 support - [@jrhe](https://github.com/jrhe).
 * Fix: document APIs at root level - [@dblock](https://github.com/dblock).
-* Added support for procs in basepath - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
+* Added support for procs in basepath - [@ruby-grape](https://github.com/ruby-grape).
 * Support both `:desc` and `:description` when describing parameters - [@dblock](https://github.com/dblock).
 * Fix: allow parameters such as `name[]` - [@dblock](https://github.com/dblock).
 
 ### 0.5.0 (March 28, 2013)
 
-* Added Grape 0.5.0 support - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
+* Added Grape 0.5.0 support - [@ruby-grape](https://github.com/ruby-grape).
 
 ### 0.4.0 (March 28, 2013)
 
@@ -151,28 +178,28 @@
 ### 0.3.0 (October 19, 2012)
 
 * Added version support - [@agileanimal](https://github.com/agileanimal), [@fknappe](https://github.com/fknappe).
-* Added support for nested parameters - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
+* Added support for nested parameters - [@ruby-grape](https://github.com/ruby-grape).
 * Added basic support for specifying parameters that need to be passed in the header - [@agileanimal](https://github.com/agileanimal).
-* Add possibility to hide the documentation paths in the generated swagger documentation - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
+* Add possibility to hide the documentation paths in the generated swagger documentation - [@ruby-grape](https://github.com/ruby-grape).
 
 ### 0.2.1 (August 17, 2012)
 
-* Added support for markdown in notes field - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
+* Added support for markdown in notes field - [@ruby-grape](https://github.com/ruby-grape).
 * Fix: compatibility with Rails - [@qwert666](https://github.com/qwert666).
-* Fix: swagger UI history - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
+* Fix: swagger UI history - [@ruby-grape](https://github.com/ruby-grape).
 
 ### 0.2.0 (July 27, 2012)
 
-* Use resource as root for swagger - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
-* Added support for file uploads, and proper `paramType` - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
+* Use resource as root for swagger - [@ruby-grape](https://github.com/ruby-grape).
+* Added support for file uploads, and proper `paramType` - [@ruby-grape](https://github.com/ruby-grape).
 * Added tests - [@nathanvda](https://github.com/nathanvda).
 
 ### 0.1.0 (July 19, 2012)
 
-* Added some configurability to the generated documentation - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
-* Adapted to rails plugin structure - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
-* Allowed cross origin, so swagger can be used from official site - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
+* Added some configurability to the generated documentation - [@ruby-grape](https://github.com/ruby-grape).
+* Adapted to rails plugin structure - [@ruby-grape](https://github.com/ruby-grape).
+* Allowed cross origin, so swagger can be used from official site - [@ruby-grape](https://github.com/ruby-grape).
 
 ### 0.0.0 (July 19, 2012)
 
-* Initial public release - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
+* Initial public release - [@ruby-grape](https://github.com/ruby-grape).

data/Gemfile

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

data/README.md

@@ -1,52 +1,76 @@
-**these branch generates a swagger file, which is conform to the 1.2 spec**
+This is work in progress for bringing grape-swagger to [swagger-spec (OpenAPI) 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) spec. Re-added/reimplemented features from [grape-swagger 1.2](https://github.com/ruby-grape/grape-swagger/tree/swagger-1.2) could be found in the ToC.
 
-compatible versions:
+##### Table of Contents
 
-- `grape <~ 0.14.0`
-- `grape-entity < 0.5.0`
+[What is grape-swagger?](#what)  
+[Related Projects](#related)  
+[Swagger-Spec](#swagger-spec)  
+[Installation](#install)  
+[Usage](#usage)  
+[Configure](#configure)  
+[Routes Configuration](#routes)  
+[Markdown](#md_usage)  
+[Response documentation](#response)  
+[Extensions](#extensions)  
+[Example](#example)  
 
-# grape-swagger
+For how to use at the moment see [v2 specs](tree/master/spec/swagger_v2) and or [Hussars](https://github.com/LeFnord/hussars) sample app.
 
 [![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=swagger-1.2)](https://travis-ci.org/ruby-grape/grape-swagger)
+[![Build Status](https://travis-ci.org/ruby-grape/grape-swagger.svg?branch=swagger-2.0)](https://travis-ci.org/ruby-grape/grape-swagger)
 [![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)
 
+<a name="what" />
 ## What is grape-swagger?
 
 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.
 
-![Demo Screenshot](example/splines.png)
+![Demo Screenshot](example/swagger-example.png)
 
+These screenshot is based on the [Hussars](https://github.com/LeFnord/hussars) sample app.
+
+
+<a name="related" />
 ## Related Projects
 
 * [Grape](https://github.com/ruby-grape/grape)
 * [Swagger UI](https://github.com/wordnik/swagger-ui)
 
+
+<a name="swagger-spec" />
 ## Swagger-Spec
 
-Grape-swagger generates documentation per [Swagger Spec 1.2](https://github.com/swagger-api/swagger-spec/blob/master/versions/1.2.md).
+Grape-swagger generates documentation per [Swagger Spec 2.0](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md).
+
 
+<a name="install" />
 ## Installation
 
 Add to your Gemfile:
 
-```gem 'grape-swagger'```
+```ruby
+  gem 'grape-swagger', git: 'git@github.com:ruby-grape/grape-swagger.git'
+```
+
 
 ## Upgrade
 
 Please see [UPGRADING](UPGRADING.md) when upgrading from a previous version.
 
+
+<a name="usage" />
 ## Usage
 
 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/api.rb](example/api.rb) for a simple demo.
 
 
-``` ruby
+```ruby
 require 'grape-swagger'
 
 module API
   class Root < Grape::API
+    format :json
     mount API::Cats
     mount API::Dogs
     mount API::Pirates
@@ -57,11 +81,12 @@ end
 
 To explore your API, either download [Swagger UI](https://github.com/wordnik/swagger-ui) and set it up yourself or go to the [online swagger demo](http://petstore.swagger.wordnik.com/) and enter your localhost url documentation root in the url field (probably something in the line of http://localhost:3000/swagger_doc).
 
+
 ### CORS
 
 If you use the online demo, make sure your API supports foreign requests by enabling CORS in Grape, otherwise you'll see the API description, but requests on the API won't return. Use [rack-cors](https://github.com/cyu/rack-cors) to enable CORS.
 
-```` ruby
+````ruby
 require 'rack/cors'
 use Rack::Cors do
   allow do
@@ -73,103 +98,181 @@ end
 
 Alternatively you can set CORS headers in a Grape `before` block.
 
-``` ruby
+```ruby
 before do
   header['Access-Control-Allow-Origin'] = '*'
   header['Access-Control-Request-Method'] = '*'
 end
 ````
 
-## Configure
 
-You can pass a hash with optional configuration settings to ```add_swagger_documentation```.
+<a name="configure" />
+## Configure
 
-#### target_class
+[host](#host)  
+[base_path](#base_path)  
+[mount_path](#mount_path)  
+[add_base_path](#add_base_path)  
+[add_version](#add_version)  
+[markdown](#markdown)  
+[api_version](#api_version)  
+[models](#models)  
+[hide_documentation_path](#hide_documentation_path)  
+[info](#info)  
 
-The API class to document, default `self`.
 
-#### mount_path
+You can pass a hash with optional configuration settings to ```add_swagger_documentation```.
 
-The path where the API documentation is loaded, default is `/swagger_doc`.
+*not all configuration options supported yet*, but is WIP
 
-#### class_name
 
-API class name.
+`host` and `base_path` are also accepting a `proc` to evaluate.
 
-#### markdown
+<a name="host" />
+#### host:
+Sets explicit the `host`
+```ruby
+add_swagger_documentation \
+   host: 'www.no-example.com'
+```
 
-Allow markdown in `detail`/`notes`, default is `nil`. (disabled) See below for details.
+<a name="base_path" />
+#### base_path:
+Base path of the API that's being exposed.
+```ruby
+add_swagger_documentation \
+   base_path: '/super/api'
+```
 
-#### i18n_scope
+<a name="mount_path" />
+#### mount_path:
+The path where the API documentation is loaded, default is `/swagger_doc`.
+```ruby
+add_swagger_documentation \
+   mount_path: '/docu'
+```
 
-Translations scope (or array of scopes) default is `:api`. [See below for details](#i18n).
+#### add_base_path:
+Add `basePath` key to the JSON documentation, default is `false`.
+```ruby
+add_swagger_documentation \
+   add_base_path: true
+```
 
-#### hide_format
+#### add_version:
+Add `version` key to the JSON documentation, default is `true`.
+```ruby
+add_swagger_documentation \
+   add_version: false
+```
 
-Don't add `.(format)` to the end of URLs, default is `false`.
 
-#### api_version
+<a name="markdown" />
+#### markdown:
+Allow markdown in `detail`, default is `false`. (disabled) See [below](#md_usage) for details.
 
-Version of the API that's being exposed.
+```ruby
+add_swagger_documentation \
+  markdown: GrapeSwagger::Markdown::KramdownAdapter.new
+```
+or alternative
+```ruby
+add_swagger_documentation \
+  markdown: GrapeSwagger::Markdown::RedcarpetAdapter.new
+```
 
-#### base_path
+<a name="api_version" />
+#### api_version:
+```ruby
+add_swagger_documentation \
+   api_version: 'v1'
+```
 
-Base path of the API that's being exposed. This configuration parameter accepts a `proc` to evaluate `base_path`, useful when you need to use request attributes to determine its value.
+Version of the API that's being exposed.
 
-#### authorizations
 
+#### *authorizations*:
 This value is added to the `authorizations` key in the JSON documentation.
 
-#### root_base_path
 
-Add `basePath` key to the JSON documentation, default is `true`.
 
-#### models
+<a name="models" />
+#### models:
+A list of entities to document. Combine with the [grape-entity](https://github.com/ruby-grape/grape-entity) gem.
 
-A list of entities to document. Combine with the [grape-entity](https://github.com/ruby-grape/grape-entity) gem. See below for details.
+These would be added to the definitions section of the swagger file.
 
-#### hide_documentation_path
-
-Don't show the `/swagger_doc` path in the generated swagger documentation.
-
-#### format
+```ruby
+add_swagger_documentation \
+   models: [
+     TheApi::Entities::UseResponse,
+     TheApi::Entities::ApiError
+   ]
+```
 
-Documentation response format, default is `:json`.
+<a name="hide_documentation_path" />
+#### hide_documentation_path: (default: `true`)
+```ruby
+add_swagger_documentation \
+   hide_documentation_path: true
+```
 
-#### info
+Don't show the `/swagger_doc` path in the generated swagger documentation.
 
-A hash merged into the `info` key of the JSON documentation. This may contain:
+<a name="info" />
+#### info:
+```ruby
+add_swagger_documentation \
+  info: {
+    title: "The API title to be displayed on the API homepage.",
+    description: "A description of the API.",
+    contact_name: "Contact name",
+    contact_email: "Contact@email.com",
+    contact_url: "Contact URL",
+    license: "The name of the license.",
+    license_url: "www.The-URL-of-the-license.org",
+    terms_of_service_url: "www.The-URL-of-the-terms-and-service.com",
+  }
+```
 
-* `:title`: The API title to be displayed on the API homepage.
-* `:description`: A description of the API.
-* `:contact`: Contact email.
-* `:license`: The name of the license.
-* `:license_url`: The URL of the license.
-* `:terms_of_service_url`: The URL of the API terms and conditions.
+A hash merged into the `info` key of the JSON documentation.
 
-#### api_documentation
 
+<!-- #### *api_documentation*:
 Customize the Swagger API documentation route, typically contains a `desc` field. The default description is "Swagger compatible API description".
 
-``` ruby
+```ruby
 add_swagger_documentation \
    api_documentation: { desc: 'Reticulated splines API swagger-compatible documentation.' }
 ```
 
-#### specific_api_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
+```ruby
 add_swagger_documentation \
    specific_api_documentation: { desc: 'Reticulated splines API swagger-compatible endpoint documentation.' }
-```
+``` -->
+
+
+<a name="routes" />
+## Routes Configuration
 
-## Swagger Header Parameters
+[Swagger Header Parameters](#headers)  
+[Hiding an Endpoint](#hiding)  
+[Defining an endpoint as array](#array)  
+[Using an options hash](#options)  
+[Specify endpoint details](#details)  
+[Response documentation](#response)  
+
+
+<a name="headers" />
+#### Swagger Header Parameters <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
+```ruby
 desc "Return super-secret information", {
   headers: {
     "XAuthToken" => {
@@ -184,69 +287,82 @@ desc "Return super-secret information", {
 }
 ```
 
-## Hiding an Endpoint
+
+<a name="hiding" />
+#### Hiding an Endpoint
 
 You can hide an endpoint by adding ```hidden: true``` in the description of the endpoint:
 
-``` ruby
+```ruby
 desc 'Hide this endpoint', hidden: true
 ```
 
 Endpoints can be conditionally hidden by providing a callable object such as a lambda which evaluates to the desired
 state:
 
-``` ruby
+```ruby
 desc 'Conditionally hide this endpoint', hidden: lambda { ENV['EXPERIMENTAL'] != 'true' }
 ```
 
-## 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.
+#### Overriding Auto-Generated Nicknames
 
-``` ruby
+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'
 ```
 
-## Defining an endpoint as array
+
+<a name="array" />
+#### Defining an endpoint as array
 
 You can define an endpoint as array by adding `is_array` in the description:
 
-``` ruby
+```ruby
 desc 'Get a full list of pets', is_array: true
 ```
 
-## Using an options hash
+
+<a name="options" />
+#### Using an options hash
 
 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:
 
-``` ruby
+```ruby
 desc 'Get all kittens!', {
-  :hidden => true,
-  :is_array => true,
-  :nickname => 'getKittens',
-  :entity => Entities::Kitten, # use entity instead of success
-  :http_codes => [[401, 'KittenBitesError', Entities::BadKitten]]  # use http_codes instead of failure
+  hidden: true,
+  is_array: true,
+  nickname: 'getKittens',
+  entity: Entities::Kitten, # or success
+  http_codes: [[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" ]
   }
 get '/kittens' do
 ```
 
-## Specify endpoint details
+
+<a name="details" />
+#### Specify endpoint details
 
 To specify further details for an endpoint, use the `detail` option within a block passed to `desc`:
 
-``` ruby
+```ruby
 desc 'Get all kittens!' do
   detail 'this will expose all the kittens'
 end
 get '/kittens' do
 ```
 
-## Overriding param type
+
+#### Overriding param type
 
 You can override paramType in POST|PUT methods to query, using the documentation hash.
 
-``` ruby
+```ruby
 params do
   requires :action, type: Symbol, values: [:PAUSE, :RESUME, :STOP], documentation: { param_type: 'query' }
 end
@@ -255,69 +371,88 @@ post :act do
 end
 ```
 
-## Expose nested namespace as standalone route
+
+#### Expose nested namespace as standalone route
+
 Use the `nested: false` property in the `swagger` option to make nested namespaces appear as standalone resources.
 This option can help to structure and keep the swagger schema simple.
 
-    namespace 'store/order', desc: 'Order operations within a store', swagger: { nested: false } do
-      get :order_id do
-      	...
-      end
-    end
+```ruby
+namespace 'store/order', desc: 'Order operations within a store', swagger: { nested: false } do
+  get :order_id do
+  	...
+  end
+end
+```
 
 All routes that belong to this namespace (here: the `GET /order_id`) will then be assigned to the `store_order` route instead of the `store` resource route.
 
-It is also possible to expose a namspace within another already exposed namespace:
-
-    namespace 'store/order', desc: 'Order operations within a store', swagger: { nested: false } do
-      get :order_id do
-      	...
-      end
-      namespace 'actions', desc: 'Order actions' do, nested: false
-        get 'evaluate' do
-          ...
-        end
-      end
-    end
+It is also possible to expose a namespace within another already exposed namespace:
 
+```ruby
+namespace 'store/order', desc: 'Order operations within a store', swagger: { nested: false } do
+  get :order_id do
+  	...
+  end
+  namespace 'actions', desc: 'Order actions' do, nested: false
+    get 'evaluate' do
+      ...
+    end
+  end
+end
+```
 Here, the `GET /order_id` appears as operation of the `store_order` resource and the `GET /evaluate` as operation of the `store_orders_actions` route.
 
-### With a custom name
+
+##### With a custom name
+
 Auto generated names for the standalone version of complex nested resource do not have a nice look.
 You can set a custom name with the `name` property inside the `swagger` option, but only if the namespace gets exposed as standalone route.
 The name should not contain whitespaces or any other special characters due to further issues within swagger-ui.
 
-    namespace 'store/order', desc: 'Order operations within a store', swagger: { nested: false, name: 'Store-orders' } do
-      get :order_id do
-      	...
-      end
-    end
+```ruby
+namespace 'store/order', desc: 'Order operations within a store', swagger: { nested: false, name: 'Store-orders' } do
+  get :order_id do
+  	...
+  end
+end
+```
 
+
+<a name="additions" />
 ## Additional documentation
 
-## Setting a Swagger defaultValue
+
+[Markdown in Detail](#md_usage)  
+[Response documentation](#response)  
+
+
+### Setting a Swagger defaultValue
 
 Grape allows for an additional documentation hash to be passed to a parameter.
 
-    params do
-      requires :id, type: Integer, desc: 'Coffee ID'
-      requires :temperature, type: Integer, desc: 'Temperature of the coffee in celcius', documentation: { example: 72 }
-    end
+```ruby
+params do
+  requires :id, type: Integer, desc: 'Coffee ID'
+  requires :temperature, type: Integer, desc: 'Temperature of the coffee in celcius', documentation: { example: 72 }
+end
+```
 
 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.
 
-
-    params do
-      requires :id, type: Integer, desc: 'Coffee ID'
-      optional :temperature, type: Integer, desc: 'Temperature of the coffee in celcius', default: 72
-    end
+```ruby
+params do
+  requires :id, type: Integer, desc: 'Coffee ID'
+  optional :temperature, type: Integer, desc: 'Temperature of the coffee in celcius', default: 72
+end
+```
 
 
-## Grape Entities
+### Grape Entities
 
-Add the [grape-entity](https://github.com/ruby-grape/grape-entity) gem to our Gemfile.
+Add the [grape-entity](https://github.com/agileanimal/grape-entity) gem to our Gemfile.
 
 The following example exposes statuses. And exposes statuses documentation adding :type and :desc.
 
@@ -331,10 +466,6 @@ module API
     end
 
     class Link < Grape::Entity
-      def self.entity_name
-        'link'
-      end
-
       expose :href, documentation: { type: 'url' }
       expose :rel, documentation: { type: 'string'}
     end
@@ -343,14 +474,17 @@ module API
   class Statuses < Grape::API
     version 'v1'
 
-    desc 'Statuses index', entity: API::Entities::Status
+    desc 'Statuses index',
+      entity: API::Entities::Status
     get '/statuses' do
       statuses = Status.all
       type = current_user.admin? ? :full : :default
       present statuses, with: API::Entities::Status, type: type
     end
 
-    desc 'Creates a new status', entity: API::Entities::Status, params: API::Entities::Status.documentation
+    desc 'Creates a new status',
+      entity: API::Entities::Status,
+      params: API::Entities::Status.documentation
     post '/statuses' do
         ...
     end
@@ -358,11 +492,13 @@ module API
 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
@@ -391,7 +527,8 @@ module API
 end
 ```
 
-#### 1x1
+
+##### 1x1
 
 Note: `is_array` is `false` by default.
 
@@ -422,63 +559,47 @@ module API
 end
 ```
 
-## Markdown in Detail/Notes
 
-The grape-swagger gem allows you to add an explanation in markdown in the detail/notes field. Which would result in proper formatted markdown in Swagger UI.
+<a name="md_usage" />
+### Markdown in Detail
+
+The grape-swagger gem allows you to add an explanation in markdown in the detail field. Which would result in proper formatted markdown in Swagger UI.
 Grape-swagger uses adapters for several markdown formatters. It includes adapters for [kramdown](http://kramdown.rubyforge.org) (kramdown [syntax](http://kramdown.rubyforge.org/syntax.html)) and [redcarpet](https://github.com/vmg/redcarpet).
 The adapters are packed in the GrapeSwagger::Markdown modules. We do not include the markdown gems in our gemfile, so be sure to include or install the depended gems.
 
+To use it, add a new instance of the adapter to the markdown options of `add_swagger_documentation`, such as:
+```ruby
+add_swagger_documentation \
+  markdown: GrapeSwagger::Markdown::KramdownAdapter.new(options)
+```
+and write your route details in GFM, examples could be find in [details spec](blob/master/spec/swagger_v2/api_swagger_v2_detail_spec.rb)
 
-### Kramdown
+
+#### Kramdown
 If you want to use kramdown as markdown formatter, you need to add kramdown to your gemfile.
 
-```
+```ruby
 gem 'kramdown'
 ```
 
 Configure your api documentation route with:
-
-
-``` ruby
-add_swagger_documentation(
-  markdown: GrapeSwagger::Markdown::KramdownAdapter
-)
+```ruby
+add_swagger_documentation \
+  markdown: GrapeSwagger::Markdown::KramdownAdapter.new(options)
 ```
 
-Finally you can write endpoint descriptions the with markdown enabled.
-
-``` ruby
-desc "Reserve a burger in heaven" do
-  detail <<-NOTE
-    Veggie Burgers in Heaven
-    -----------------
-
-    > A veggie burger doesn't come for free
-
-    If you want to reserve a veggie burger in heaven, you have to do
-    some crazy stuff on earth.
 
-        def do_good
-          puts 'help people'
-        end
-
-    * _Will go to Heaven:_ Probably
-    * _Will go to Hell:_ Probably not
-  NOTE
-end
-```
-
-### Redcarpet
+#### Redcarpet
 As alternative you can use [redcarpet](https://github.com/vmg/redcarpet) as formatter, you need to include redcarpet in your gemspec. If you also want to use [rouge](https://github.com/jneen/rouge) as syntax highlighter you also need to include it.
 
-```
+```ruby
 gem 'redcarpet'
 gem 'rouge'
 ```
 
 Configure your api documentation route with:
 
-``` ruby
+```ruby
 add_swagger_documentation(
   markdown: GrapeSwagger::Markdown::RedcarpetAdapter.new(render_options: { highlighter: :rouge })
 )
@@ -486,13 +607,16 @@ add_swagger_documentation(
 
 Alternatively you can disable rouge by adding `:none` as highlighter option. You can add redcarpet extensions and render options trough the `extenstions:` and `render_options:` parameters.
 
-### Custom markdown formatter
+
+#### Custom markdown formatter
+
 You can also add your custom adapter for your favourite markdown formatter, as long it responds to the method `markdown(text)` and it formats the given text.
 
-``` ruby
+
+```ruby
 module API
 
-  class MySuperbMarkdownFormatterAdapter
+  class FancyAdapter
    attr_reader :adapter
 
    def initialize(options)
@@ -505,212 +629,175 @@ module API
    end
   end
 
-  add_swagger_documentation markdown: MySuperbMarkdownFormatterAdapter.new(no_links: true)
+  add_swagger_documentation markdown: FancyAdapter.new(no_links: true)
 end
-
 ```
 
+
+<a name="response" />
 ## Response documentation
 
-You can also document the HTTP status codes with a description and a specified model that your API returns with the following syntax.
+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.
 
-``` ruby
-get '/', http_codes: [
-  [200, 'Ok', Entities::Client],
-  [400, "Invalid parameter entry"]
-] do
+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
 ```
 
-## I18n
+```ruby
+desc 'thing' do
+  params Entities::Something.documentation
+  http_codes [ { code: 400, message: "Invalid parameter entry" } ]
+end
+get '/thing' do
+  ...
+end
+```
 
-Grape-swagger supports I18n for most messages of the JSON documentation, including:
+```ruby
+get '/thing', http_codes: [
+  { code: 200, message: 'Ok' },
+  { code: 400, message: "Invalid parameter entry" }
+] do
+  ...
+end
+```
 
-* API [info](#info)
-* Namespaces/resources description
-* Endpoints description and detail/notes
-* Params (including headers) description
-* Models/entities description
+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.
 
-By default, grape-swagger will lookup translations inside `:api` scope. This can be configured by
-set [`i18n_scope`](#i18n_scope) to a custom scope (or an array of scopes) when calling
-`add_swagger_documentation`.
+The result is then something like following:
 
-### Translation and Default Message
+```json
+"responses": {
+  "200": {
+    "description": "get Horses",
+    "schema": {
+      "$ref": "#/definitions/Thing"
+    }
+  },
+  "401": {
+    "description": "HorsesOutError",
+    "schema": {
+      "$ref": "#/definitions/ApiError"
+    }
+  }
+},
+```
 
-To localize your API document, you can add a locale file containing translated messages.
-Grape-swagger will try to look up translation for each message. If a translation cannot be found,
-it will use the message specified in the API code, then default to blank.
+<a name="extensions" />
+## Extensions
 
-Take the following sample API for example:
+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 'Gets all kittens' do
-  detail 'This will expose all the kittens.'
-end
-params do
-  optional :sort
-end
-get :kittens do
-end
+desc 'This returns something with extension on verb level',
+  x: { some: 'stuff' }
+```
+this would generate:
+```json
+"/path":{
+  "get":{
+    "…":"…",
+    "x-some":"stuff"
+  }
+}
 ```
 
-To generate I18n documentation, you can add a locale file with translated messages:
+- `path` extension, by setting via route settings:
+```ruby
+route_setting :x_path, { some: 'stuff' }
+```
+this would generate:
+```json
+"/path":{
+  "x-some":"stuff",
+  "get":{
+    "…":"…",
+  }
+}
+```
 
-```yaml
-api:
-  kittens:
-    get:
-      detail: This will return a full list of kittens, and you can change the way of sorting them.
-      params:
-        sort: Specifies the order of results
+- `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' }]
 ```
 
-The endpoint description in generated API document will be "Gets all kittens" - specified in source
-code - because there is no translation defined. And endpoint details will be overwritten by locale
-message - "This will return a full list of kittens, and you can change the way of sorting them.".
-Parameter `:sort` will have a description from locale file too.
+<a="example" />
+# Example
 
-### Default Lookup Keys
+Go into example directory and run it: `$ bundle exec rackup`
+go to: `http://localhost:9292/swagger_doc` to get it
 
-The following lookup keys are all within the scope given by `i18n_scope`.
+For request examples load the [postman file]()
+## Grouping the API list using Namespace
 
-#### API Info
+Use namespace for grouping APIs
 
-The default lookup key of a field in API info is `info.<field>`, i.e.:
+![grape-swagger-v2-new-corrected](https://cloud.githubusercontent.com/assets/1027590/13516020/979cfefa-e1f9-11e5-9624-f4a6b17a3c8a.png)
 
-* `info.title` for `:title` field.
-* `info.desc` or `info.description` for `:description` field.
-* `info.contact` for `:contact` field.
-* `info.license` for `:license` field.
-* `info.license_url` for `:license_url` field.
-* `info.terms_of_service_url` for `:terms_of_service_url` field.
+# Example
 
-#### Namespaces/Resources Description
+```ruby
+class NamespaceApi < Grape::API
+  namespace :hudson do
+    desc 'Document root'
+    get '/' do
+    end
+  end
 
-Grape-swagger will give each root namespace a default description, such as "*Operations about
-users*", where `users` is a namespace (pluralized). But you can change it by provide your own
-message under key `<namespace>.desc` or `<namespace>.description` in your locale file. And the
-namespace itself is available as a variable for interpolation.
+  namespace :hudson do
+    desc 'This gets something.',
+      notes: '_test_'
 
-### Endpoints Description and Detail/Notes
+    get '/simple' do
+      { bla: 'something' }
+    end
+  end
 
-An endpoint's default lookup key is in format of `<namespace>.<path>.<http_method>`. And if there
-are nested namespaces or multi-level path, all parts will be join by `.`. For example for this
-endpoint:
+  namespace :colorado do
+    desc 'This gets something for URL using - separator.',
+      notes: '_test_'
 
-```ruby
-namespace :users do
-  route_params :id do
-    get :'password/strength' do
+    get '/simple-test' do
+      { bla: 'something' }
     end
   end
 end
-```
+  …
 
-Its corresponding lookup key will be `users.:id.password.strength.get`, let's say that this is
-the key of this endpoint.
-
-So an endpoint's description message can be given under `<endpoint_key>.desc` or
-`<endpoint_key>.description`. And use `<endpoint_key>.detail` or `<endpoint_key>.notes` for the
-message of its further details.
-
-#### Params Description
-
-The first default key of endpoint parameter's description translation is
-`<endpoint_key>.params.<param_name>`. But considering that some endpoints could usually share a
-same parameter, it will be a little annoyed to duplicate its description message everywhere. So if
-no translation found in the first default key, grape-swagger will try to find all its parent keys.
-Take above endpoint for example, it may have a parameter named `:id`, then the lookup keys are:
-
-1. `users.:id.password.strength.get.params.id`
-1. `users.:id.password.strength.params.id`
-1. `users.:id.password.params.id`
-1. `users.:id.params.id`
-1. `users.params.id`
-1. `params.id`
-
-#### Models/Entities Description
-
-A model class' lookup key is by default its class name, without module part, and underscored. Each
-property's key is then `entities.<class_key>.<property_name>`. When not found, grape-swagger will
-try to check the its ancestors, up to a class whose name is `Entity`.
-
-Say if there is model class `User` inherits `Grape::Entity`, and another model `AdminUser` inherits
-`User`, to translate a property named `:email` of `AdminUser`, the lookup keys are:
-
-1. `entities.admin_user.email`
-1. `entities.user.email`
-1. `entities.default.email`
-
-#### Example Locale File
-
-```yaml
-en:
-  api:
-    info:
-      title: My Awesome API
-      desc: Some detail information about this API.
-    entities:
-      default:
-        id: Resource identifier
-      user:
-        name: User's real name
-        email: User's login email address
-        sign_up_at: When the user signed up
-      admin_user:
-        level: Which level the admin is
-      password_strength:
-        level: A 0~4 integer indicates `very_weak` to `strong`
-        crack_time: An estimated time for force cracking the password, in seconds
-    params:
-      locale: Used to change locale of endpoint's responding message
-      sort: To specify the order of result list, default is %{default_sort}
-    users:
-      desc: Operations about not-disabled users
-      get:
-        desc: Gets a list of users
-        detail: You can control how to sort the results.
-      ':id':
-        params:
-          id: User id
-        get:
-          desc: Finds user by id
-        email:
-          put:
-            desc: Changes a user's email
-            params:
-              email: A new email
-        password:
-          strength:
-            get:
-              desc: Gets the strength estimation of a user's password
-              detail: The estimation is done by a well-known algorithm when he changed his password
-    swagger_doc:
-      desc: Endpoints for API documents
-      get:
-        desc: Gets root API document
-      ':name':
-        get:
-          desc: Gets specific resource API document
-          params:
-            name: Resource name
-```
-
-### Customization
-
-The translation can be customized by using different kind/format of message in source code.
-
-* A string or `nil`: It will become the default message when a translation is not defined.
-* A symbol: Looks up translation using the symbol as a key, but will fallback to default key(s).
-* A hash with the following keys:
-  * key: A symbol, defines custom lookup key.
-  * default: A string, defines the default message when translation can not be found.
-  * translate: A boolean (default is `true`), set to `false` to skip translation for this message.
-  * scope: A symbol, or a string, or an array of them. Used to replace the `i18n_scope` config
-    value for a custom lookup scope.
-  * Any other key/value will be sent to the translation function for interpolation.
+```
 
 ## Contributing to grape-swagger