apipie-rails 0.5.7 → 0.5.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c873515d61e1046750c0ecd967b30f289ac9e3ee
-  data.tar.gz: 1bfaf2d71ca3b995045cf2be2c75e6cf846e25fa
+  metadata.gz: 97d15ca9f95ac7fc79b848f3a3207c22c8e69f4c
+  data.tar.gz: 5d0dcae7fea76412efec316d2774da51367cee44
 SHA512:
-  metadata.gz: 56d02246c13676a616393bd28a25e297e757aa95ce3b41f6e4f6914cb966afa71ade2eb49ca3b53a39fbbccac3b81bd840e212ef9479de687d628d128626d8d3
-  data.tar.gz: 238da70119f0ce29b87ad54b9e0dd903aac41314c79095c75799aeb7226b7ef2abaf78b361e72e7821281dd3e1c21e60a7f5952f51fcff4cb016705ebd993e95
+  metadata.gz: 8716a1ebb09f66511232cdc45756cef0794791b618ae0dec4c1455e25cc194a5e5ab6ae9ec49c4845d6390f969785f4fe1f69b7d0e783c903cbce0f21c4f4b71
+  data.tar.gz: 63a0482166b36b1d6c8e2d066b67cd76242495111a0a79296576a7505adf22070a8515ddef1d9136c91f2b502059e0a3a5b1a358ebc7e1cd4d75b0c8439b2537

data/CHANGELOG.md

@@ -1,6 +1,14 @@
  Changelog
 ===========
 
+v0.5.8
+------
+
+- Swagger json includes apipie's description as swagger's description [\#615](https://github.com/Apipie/apipie-rails/pull/615) ([gogotanaka](https://github.com/gogotanaka))
+- Fix api! issue by using underscore when appending `controller` to the default controller string [\#613](https://github.com/Apipie/apipie-rails/pull/613) ([kevinmarx](https://github.com/kevinmarx))
+- Possibility to compress examples [\#600](https://github.com/Apipie/apipie-rails/pull/600) ([Haniyya](https://github.com/Haniyya))
+- Possibility to describe responses [\#588](https://github.com/Apipie/apipie-rails/pull/588) ([elasti-ron](https://github.com/elasti-ron))
+
 v0.5.7
 ------
 

data/PROPOSAL_FOR_RESPONSE_DESCRIPTIONS.md

@@ -0,0 +1,244 @@
+# Proposal for supporting response descriptions in Apipie
+
+## Rationale
+
+Swagger allows API authors to describe the structure of objects returned by REST API calls.
+Client authors and code generators can use such descriptions for various purposes, such as verification, 
+autocompletion, and so forth.
+
+The current Apipie DSL allows API authors to indicate returned error codes (using the `error` keyword), 
+but does not support descriptions of returned data objects. As such, swagger files
+generated from the DSL do not include those, and are somewhat limited in their value.
+
+This document proposes a minimalistic approach to extending the Apipie DSL to allow description of response
+objects, and including those descriptions in generated swagger files. 
+
+## Design Objectives
+
+* Full backward compatibility with the existing DSL
+* Minimal implementation effort
+* Enough expressiveness to support common use cases
+* Optional integration of the DSL with advanced JSON generators (such as Grape-Entity)   
+* Allowing developers to easily verify that actual responses match the response declarations   
+
+## Approach
+
+#### Add a `returns` keyword to the DSL, based on the existing `error` keyword
+
+Currently, returned error codes are indicated using the `error` keyword, for example:
+```ruby
+api :GET, "/users/:id", "Show user profile"
+error :code => 401, :desc => "Unauthorized"
+```
+
+The proposed approach is to add a `returns` keyword, that has the following syntax:
+```ruby
+returns <type-identifier> [, :code => <number>] [, :desc => <response-description>]
+```
+
+For example:
+```ruby
+api :GET, "/users/:id", "Show user profile"
+error :code => 401, :desc => "Unauthorized"
+returns :SomeTypeIdentifier  # :code is not specified, so it is assumed to be 200
+```
+
+
+#### Leverage `param_group` for response object description
+
+Apipie currently has a mechanism for describing complex objects using the `param_group` keyword.
+It seems reasonable to leverage this mechanism as the basis of the response object description mechanism,
+so that the `<type-identifier>` in the `returns` keyword will be the name of a param_group.
+
+For example:
+```ruby
+  def_param_group :user do
+    param :user, Hash, :desc => "User info", :required => true, :action_aware => true do
+      param_group :credentials
+      param :membership, ["standard","premium"], :desc => "User membership", :allow_nil => false
+    end
+  end
+
+  api :GET, "/users/:id", "Get user record"
+  returns :user, "the requested record"
+  error :code => 404, :desc => "no user with the specified id"
+```
+
+Implementation of this DSL extension would involve - as part of the implementation of the `returns` keyword - 
+the generation of a Apipie::ParamDescription object that has a Hash validator pointing to the param_group block.
+
+#### Extend action-aware functionality to include 'response-only' parameters
+
+In CRUD operations, it is common for `param_group` input definitions to be very similar to the 
+output of the API, with the exception of a very small number of fields (such as the `:id` field
+which usually appears in the response, but is not described in the `param_group` because it is passed as a 
+path parameter).
+
+To allow reuse of the `param_group`, it would be useful to its definition to describe parameters that are not passed 
+in the request but are returned in the response.  This would be implementing by extending the DSL to 
+support a `:only_in => :response` option on `param` definitions.  Similarly, params could be defined to be 
+`:only_in => :request` to indicate that they will not be included in the response.    
+
+For example:
+```ruby
+  # in the following group, the :id param is ignored in requests, but included in responses
+  def_param_group :user do
+    param :user, Hash, :desc => "User info", :required => true, :action_aware => true do
+      param :id, Integer, :only_in => :response
+      param :requested_id, Integer, :only_in => :request
+      param_group :credentials
+      param :membership, ["standard","premium"], :desc => "User membership", :allow_nil => false
+    end
+  end
+
+  api :GET, "/users/:id", "Get user record"
+  returns :user, :desc => "the requested record"  # includes the :id field, because this is a response
+  error :code => 404, :desc => "no user with the specified id"
+```
+
+
+#### Support `:array_of => <param_group-name>` in the `returns` keyword 
+
+Very often, a REST API call returns an array of some previously-defined object 
+(the most common example an `index` operation that returns an array of the same entity returned by a `show` request), 
+and it would be tedious to have to define a separate `param_group` for each one.
+
+For added convenience, the `returns` keyword will also support an `:array_of =>` construct
+to specify that an API call returns an array of some object type.
+
+For example:
+```ruby
+  api :GET, "/users", "Get all user records"
+  returns :array_of => :user, :desc => "the requested user records"
+
+  api :GET, "/user/:id", "Get a single user record"
+  returns :user, :desc => "the requested user record"
+```
+
+#### Integration with advanced JSON generators using an [adapter](https://en.wikipedia.org/wiki/Adapter_pattern) to `param_group`
+
+While it makes sense for the sake of simplicity to leverage the `param_group` construct to describe 
+returned objects, it is likely that many developers will prefer to unify the 
+description of the response with the actual generation of the JSON.
+
+Some JSON-generation libraries, such as [Grape-Entity](https://github.com/ruby-grape/grape-entity),
+provide a declarative interface for describing an object model, allowing both runtime
+generation of the response, as well as the ability to traverse the description to auto-generate
+documentation.
+
+Such libraries could be integrated with Apipie using adapters that wrap the library-specific
+object description and expose an API that includes a `params_ordered` method that behaves in a 
+similar manner to [`Apipie::HashValidator.params_ordered`](https://github.com/Apipie/apipie-rails/blob/cfb42198bc39b5b30d953ba5a8b523bafdb4f897/lib/apipie/validator.rb#L315).
+Such an adapter would make it possible to pass an externally-defined entity to the `returns` keyword
+as if it were a `param_group`.
+
+Such adapters can be created easily by having a class respond to `#describe_own_properties` 
+with an array of property description objects.  When such a class is specified as the 
+parameter to a `returns` declaration, Apipie would query the class for its properties
+by calling `<Class>#describe_own_properties`. 
+
+For example:
+```ruby
+# here is a class that can describe itself to Apipie
+class Animal
+  def self.describe_own_properties
+    [
+        Apipie::prop(:id, Integer, {:description => 'Name of pet', :required => false}),
+        Apipie::prop(:animal_type, 'string', {:description => 'Type of pet', :values => ["dog", "cat", "iguana", "kangaroo"]}),
+        Apipie::additional_properties(false)
+    ]
+  end
+  
+  attr_accessor :id
+  attr_accessor :animal_type  
+end
+
+# Here is an API defined as returning Animal objects.
+# Apipie creates an internal adapter by querying Animal#describe_own_properties
+api :GET, "/animals", "Get all records"
+returns :array_of => Animal, :desc => "the requested records"
+```
+
+The `#describe_own_properties` mechanism can also be used with reflection so that a
+class would query its own properties and populate the response to `#describe_own_properties`
+automatically.  See [this gist](https://gist.github.com/elasti-ron/ac145b2c85547487ca33e5216a69f527)  
+for an example of how Grape::Entity classes can automatically describe itself to Apipie
+
+#### Response validation
+
+The swagger definitions created by Apipie can be used to auto-generate clients that access the
+described APIs.  Those clients will break if the responses returned from the API do not match
+the declarations.  As such, it is very important to include unit tests that validate the actual
+responses against the swagger definitions.
+
+The ~~proposed~~ implemented mechanism provides two ways to include such validations in RSpec unit tests:
+manual (using an RSpec matcher) and automated (by injecting a test into the http operations 'get', 'post', 
+raising an error if there is no match).
+
+Example of the manual mechanism:
+
+```ruby
+require 'apipie/rspec/response_validation_helper'
+
+RSpec.describe MyController, :type => :controller, :show_in_doc => true do
+
+describe "GET stuff with response validation" do
+  render_views   # this makes sure the 'get' operation will actually
+                 # return the rendered view even though this is a Controller spec
+
+  it "does something" do
+    response = get :index, {format: :json}
+
+    # the following expectation will fail if the returned object
+    # does not match the 'returns' declaration in the Controller,
+    # or if there is no 'returns' declaration for the returned
+    # HTTP status code
+    expect(response).to match_declared_responses
+  end
+end
+```
+
+
+Example of the automated mechanism:
+```ruby
+require 'apipie/rspec/response_validation_helper'
+
+RSpec.describe MyController, :type => :controller, :show_in_doc => true do
+
+describe "GET stuff with response validation" do
+  render_views
+  auto_validate_rendered_views
+
+  it "does something" do
+    get :index, {format: :json}
+  end
+  it "does something else" do
+    get :another_index, {format: :json}
+  end
+end
+
+describe "GET stuff without response validation" do
+  it "does something" do
+    get :index, {format: :json}
+  end
+  it "does something else" do
+    get :another_index, {format: :json}
+  end
+end
+```
+
+Explanation of the implementation approach:
+
+The Apipie Swagger Generator is enhanced to allow extraction of the JSON schema of the response object
+for any controller#action[http-status].  When validation is required, the validator receives the 
+actual response object (along with information about the controller, action and http status code),
+queries the swagger generator to get the schema, and uses the json-schema validator (gem) to validate
+one against the other.
+
+Note that there is a slight complication here:  while supported by JSON-shema, the Swagger 2.0 
+specification does not support a mechanism to declare that fields in the response could be null.  
+As such, for a response that contains `null` fields, if the exact same schema used in the swagger def 
+is passed to the json-schema validator, the validation fails.  To work around this issue, when asked 
+to provide the schema for the purpose of response validation (i.e., not for inclusion in the swagger),
+the Apipie Swagger Generator creates a slightly modified schema which declares null values to be valid.
+ 

data/README.rst

@@ -117,6 +117,9 @@ desc (also description and full_description)
 param
   Common params for all methods defined in controller/child controllers.
 
+returns
+  Common responses for all methods defined in controller/child controllers.
+
 api_base_url
   What URL is the resource available under.
 
@@ -156,6 +159,9 @@ Example:
      error 404, "Missing"
      error 500, "Server crashed for some <%= reason %>", :meta => {:anything => "you can think of"}
      error :unprocessable_entity, "Could not save the entity."
+     returns :code => 403 do
+        property :reason, String, :desc => "Why this was forbidden"
+     end
      meta :author => {:name => 'John', :surname => 'Doe'}
      deprecated false
      description <<-EOS
@@ -211,7 +217,10 @@ api_versions (also api_version)
   What version(s) does the action belong to. (See `Versioning`_ for details.)
 
 param
-  Look at Parameter description section for details.
+  Look at `Parameter description`_ section for details.
+
+returns
+  Look at `Response description`_ section for details.
 
 formats
   Method level request / response formats.
@@ -261,6 +270,13 @@ Example:
      val == "param value" ? true : "The only good value is 'param value'."
    }, :desc => "proc validator"
    param :param_with_metadata, String, :desc => "", :meta => [:your, :custom, :metadata]
+   returns :code => 200, :desc => "a successful response" do
+      property :value1, String, :desc => "A string value"
+      property :value2, Integer, :desc => "An integer value"
+      property :value3, Hash, :desc => "An object" do
+        property :enum1, ['v1', 'v2'], :desc => "One of 2 possible string values"
+      end
+   end
    description "method description"
    formats ['json', 'jsonp', 'xml']
    meta :message => "Some very important info"
@@ -271,7 +287,6 @@ Example:
      #...
    end
 
-
 Parameter Description
 ---------------------
 
@@ -309,6 +324,13 @@ missing_message
   Specify the message to be returned if the parameter is missing as a string or Proc.
   Defaults to ``Missing parameter #{name}`` if not specified.
 
+only_in
+   This can be set to ``:request`` or ``:response``.
+   Setting to ``:response`` causes the param to be ignored when used as part of a request description.
+   Setting to ``:request`` causes this param to be ignored when used as part of a response description.
+   If ``only_in`` is not specified, the param definition is used for both requests and responses.
+   (Note that the keyword ``property`` is similar to ``param``, but it has a ``:only_in => :response`` default).
+
 Example:
 ~~~~~~~~
 
@@ -429,6 +451,291 @@ with ``allow_nil`` set explicitly don't have this value changed.
 Action awareness is inherited from ancestors (in terms of
 nested params).
 
+
+Response Description
+--------------------
+
+The response from an API call can be documented by adding a ``returns`` statement to the method
+description.  This is especially useful when using Apipie to auto-generate a machine-readable Swagger
+definition of your API (see the `swagger`_ section for more details).
+
+A ``returns`` statement has several possible formats:
+
+.. code:: ruby
+
+    # format #1:  reference to a param-group
+    returns <param-group-name> [, :code => <number>|<http-response-code-symbol>] [, :desc => <human-readable description>]
+
+    # format #2:  inline response definition
+    returns :code => <number>|<http-response-code-symbol> [, :desc => <human-readable description>] do
+        # property ...
+        # property ...
+        # param_group ...
+    end
+
+    # format #3:  describing an array-of-objects response
+    returns :array_of => <param-group-name> [, :code => <number>|<http-response-code-symbol>] [, :desc => <human-readable description>]
+
+
+If the ``:code`` argument is ommitted, ``200`` is used.
+
+
+Example
+~~~~~~~
+
+.. code:: ruby
+
+  # ------------------------------------------------
+  # Example of format #1 (reference to param-group):
+  # ------------------------------------------------
+  # the param_group :pet is defined here to describe the output returned by the method below.
+  def_param_group :pet do
+    property :pet_name, String, :desc => "Name of pet"
+    property :animal_type, ['dog','cat','iguana','kangaroo'], :desc => "Type of pet"
+  end
+
+  api :GET, "/pets/:id", "Get a pet record"
+  returns :pet, :desc => "The pet"
+  def show_detailed
+    render JSON({:pet_name => "Skippie", :animal_type => "kangaroo"})
+  end
+
+  # ------------------------------------------------
+  # Example of format #2 (inline):
+  # ------------------------------------------------
+  api :GET, "/pets/:id/with-extra-details", "Get a detailed pet record"
+  returns :code => 200, :desc => "Detailed info about the pet" do
+    param_group :pet
+    property :num_legs, Integer, :desc => "How many legs the pet has"
+  end
+  def show
+    render JSON({:pet_name => "Barkie", :animal_type => "iguana", :legs => 4})
+  end
+
+  # ------------------------------------------------
+  # Example of format #3 (array response):
+  # ------------------------------------------------
+  api :GET, "/pets", "Get all pet records"
+  returns :array_of => :pet, :code => 200, :desc => "All pets"
+  def index
+    render JSON([ {:pet_name => "Skippie", :animal_type => "kangaroo"},
+                  {:pet_name => "Woofie", :animal_type => "cat"} ])
+  end
+
+
+Note the use of the ``property`` keyword rather than ``param``.  This is the
+preferred mechanism for documenting response-only fields.
+
+
+The Property keyword
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+``property`` is very similar to ``param`` with the following differences:
+
+* a ``property`` is ``:only_in => :response`` by default
+
+* a ``property`` is ``:required => :true`` by default
+
+* a ``property`` can be an ``:array_of`` objects
+
+Example
+_______
+.. code:: ruby
+
+    property :example, :array_of => Hash do
+      property :number1, Integer
+      property :number2, Integer
+    end
+
+
+Describing multiple return codes
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+To describe multiple possible return codes, the ``:returns`` keyword can be repeated as many times as necessary
+(once for each return code).  Each one of the ``:returns`` entries can specify a different response format.
+
+Example
+_______
+
+.. code:: ruby
+
+    api :GET, "/pets/:id/extra_info", "Get extra information about a pet"
+      returns :desc => "Found a pet" do
+        param_group :pet
+        property 'pet_history', Hash do
+          param_group :pet_history
+        end
+      end
+      returns :code => :unprocessable_entity, :desc => "Fleas were discovered on the pet" do
+        param_group :pet
+        property :num_fleas, Integer, :desc => "Number of fleas on this pet"
+      end
+      def show_extra_info
+        # ... implementation here
+      end
+
+
+
+Reusing a param_group to describe inputs and outputs
+::::::::::::::::::::::::::::::::::::::::::::::::::::
+
+In many cases (such as CRUD implementations), the output from certain API calls is very similar - but not
+identical - to the inputs of the same or other API calls.
+
+If you already have a ``:param_group`` that defines the input to a `create` or `update` routine, it would be quite
+frustrating to have to define a completely separate ``:param_group`` to describe the output of the `show` routine.
+
+To address such situations, it is possible to define a single ``:param_group`` which combines ``param`` and ``property``
+statements (as well as ``:only_in => :request`` / ``:only_in => :response``) to differentiate between fields that are
+only expected in the request, only included in the response, or common to both.
+
+This is somewhat analogous to the way `Action Aware params`_ work.
+
+Example
+_______
+
+.. code:: ruby
+
+    def_param_group :user_record
+        param :name, String                                         # this is commong to both the request and the response
+        param :force_update, [true, false], :only_in => :request    # this does not show up in responses
+        property :last_login, String                                # this shows up only in the response
+    end
+
+   api :POST, "/users", "Create a user"
+   param_group :user_record  # the :last_login field is not expected here, but :force_update is
+   def create
+     # ...
+   end
+
+   api :GET, "/users", "Create a user"
+   returns :array_of => :user_record  # the :last_login field will be included in the response, but :force_update will not
+   def index
+     # ...
+   end
+
+
+Embedded response descriptions
+::::::::::::::::::::::::::::::
+
+If the code creating JSON responses is encapsulated within dedicated classes, it can be more convenient to
+place the response descriptions outside of the controller and embed them within the response generator.
+
+To support such use cases, Apipie allows any class to provide a `describe_own_properties` class method which
+returns a description of the properties such a class would expose.  It is then possible to specify that
+class in the `returns` statement instead of a `param_group`.
+
+The `describe_own_properties` method is expected to return an array of `Apipie::prop` objects, each one
+describing a single property.
+
+Example
+_______
+
+.. code:: ruby
+
+    class Pet
+      # this method is automatically called by Apipie when Pet is specified as the returned object type
+      def self.describe_own_properties
+        [
+            Apipie::prop(:pet_name, 'string', {:description => 'Name of pet', :required => false}),
+            Apipie::prop(:animal_type, 'string', {:description => 'Type of pet', :values => ["dog", "cat", "iguana", "kangaroo"]}),
+            Apipie::additional_properties(false)  # this indicates that :pet_name and :animal_type are the only properties in the response
+        ]
+      end
+
+      # this method w
+      def json
+        JSON({:pet_name => @name, :animal_type => @type })
+      end
+    end
+
+
+    class PetsController
+        api :GET, "/index", "Get all pets"
+        returns :array_of => Pet  # Pet is a 'self-describing-class'
+        def index
+         # ...
+        end
+    end
+
+
+A use case where this is very useful is when JSON generation is done using a reflection mechanism or some
+other sort of declarative mechanism.
+
+
+
+
+The `Apipie::prop` function expects the following inputs:
+
+.. code:: ruby
+
+    Apipie::prop(<property-name>, <property-type>, <options-hash> [, <array of sub-properties>])
+
+    # property-name should be a symbol
+    #
+    # property-type can be any of the following strings:
+    #   "integer": maps to a swagger "integer" with an "int32" format
+    #   "long": maps to a swagger "integer" with an "int64" format
+    #   "number": maps to a swagger "number"(no format specifier)
+    #   "float": maps to a swagger "number" with a "float" format
+    #   "double": maps to a swagger "number" with a "double" format
+    #   "string": maps to a swagger "string" (no format specifier)
+    #   "byte": maps to a swagger "string" with a "byte" format
+    #   "binary": maps to a swagger "string" with a "binary" format
+    #   "boolean": maps to a swagger "boolean" (no format specifier)
+    #   "date": maps to a swagger "string" with a "date" format
+    #   "dateTime": maps to a swagger "string" with a "date-time" format
+    #   "password": maps to a swagger "string" with a "password" format
+    #   "object": the property has sub-properties. include <array of sub-properties> in the call.
+    # (see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types for more information
+    # about the mapped swagger types)
+    #
+    # options-hash can include any of the options fields allowed in a :returns statement.
+    # additionally, it can include the ':is_array => true', in which case the property is understood to be
+    # an array of the described type.
+
+
+
+To describe an embedded object:
+
+.. code:: ruby
+
+
+    #
+    # PetWithMeasurements is a self-describing class with an embedded object
+    #
+    class PetWithMeasurements
+      def self.describe_own_properties
+        [
+            Apipie::prop(:pet_name, 'string', {:description => 'Name of pet', :required => false}),
+            Apipie::prop('animal_type', 'string', {:description => 'Type of pet', :values => ["dog", "cat", "iguana", "kangaroo"]}),
+            Apipie::prop(:pet_measurements, 'object', {}, [
+                Apipie::prop(:weight, 'number', {:description => "Weight in pounds" }),
+                Apipie::prop(:height, 'number', {:description => "Height in inches" }),
+                Apipie::prop(:num_legs, 'number', {:description => "Number of legs", :required => false }),
+                Apipie::additional_properties(false)
+            ])
+        ]
+      end
+    end
+
+    #
+    # PetWithManyMeasurements is a self-describing class with an embedded array of objects
+    #
+    class PetWithManyMeasurements
+      def self.describe_own_properties
+        [
+            Apipie::prop(:pet_name, 'string', {:description => 'Name of pet', :required => false}),
+            Apipie::prop(:many_pet_measurements, 'object', {is_array: true}, [
+                Apipie::prop(:weight, 'number', {:description => "Weight in pounds" }),
+                Apipie::prop(:height, 'number', {:description => "Height in inches" }),
+            ])
+        ]
+      end
+    end
+
+
+
 Concerns
 --------
 
@@ -550,6 +857,9 @@ app_name
 copyright
   Copyright information (shown in page footer).
 
+compress_examples
+  If ``true`` recorded examples are compressed using ``Zlib``. Useful for big test-suits.
+
 doc_base_url
   Documentation frontend base url.
 
@@ -1154,6 +1464,8 @@ If, for some complex cases, you need to generate/re-generate just part of the ca
 use ``rake apipie:cache cache_part=index`` resp. ``rake apipie:cache cache_part=resources``
 To generate it for different locations for further processing use ``rake apipie:cache OUT=/tmp/apipie_cache``.
 
+.. _Swagger:
+
 ====================================
  Static Swagger (OpenAPI 2.0) files
 ====================================
@@ -1236,6 +1548,11 @@ There are several configuration parameters that determine the structure of the g
 
     If ``nil`` then then host field will not be included.
 
+``config.swagger_allow_additional_properties_in_response``
+    If ``false`` (default):  response descriptions in the generated swagger will include an ``additional-properties: false``
+    field
+
+    If ``true``:  the ``additional-properties: false`` field will not be included in response object descriptions
 
 
 Known limitations of the current implementation
@@ -1246,6 +1563,7 @@ Known limitations of the current implementation
 * It is not possible to specify the "consumed" content type on a per-method basis
 * It is not possible to leverage all of the parameter type/format capabilities of swagger
 * Only OpenAPI 2.0 is supported
+* Responses are defined inline and not as a $ref
 
 ====================================
  Dynamic Swagger generation