Support validation against specs in docstrings

[roo-oliv]

Despite Flasgger supports defining the specs in the docstring, when one wants automatic POST requests data validation it is not supported doing so if the swagger specifications are defined in the docstring.

This PR adds support for that through a new validate annotation:

swagger = Swagger(app)

@app.route('/pets', methods=['POST'])
@swagger.validate('Pet')
def post():
    """
    Pet POST endpoint
    ---
    tags:
      - pet
    parameters:
      - name: body
        in: body
        required: true
        schema:
          id: Pet
          required:
            - name
          properties:
            name:
              type: string
              description: The pet's name.
              default: "Rex"
            tags:
              type: array
              description: optional list of tags
              default: ["bulldog"]
              items:
                type: string

    responses:
      200:
        description: A single pet item
        schema:
          $ref: '#/definitions/Pet'
    """
    return db.insert(request.data)

[coveralls]

Coverage decreased (-0.7%) to 81.848% when pulling b85cde3 on allrod5:validation-from-docstring into 316cc6e on rochacbruno:master.

[coveralls]

Coverage increased (+10.5%) to 93.031% when pulling a366bae on allrod5:validation-from-docstring into 316cc6e on rochacbruno:master.

[coveralls]

Coverage increased (+10.5%) to 93.031% when pulling a366bae on allrod5:validation-from-docstring into 316cc6e on rochacbruno:master.

[creising]

I was recently trying to use this feature and I ran into an issue. It looks like if I reference a definition in the schema instead of defining the object there I get the following error Filepath or specs is needed to validate. I use this same object in a couple of different methods so I only want to define it in one of them (e.g. the same validation may be used on both a POST or a PUT).

Here is a quick example:
The schema attribute post looks something like

        schema:
          "$ref": "#/definitions/ExampleObject"

Thanks!

[shivamMg]

@creising I too found out that this doesn't work. There's an open issue around that: #464.

Eventually I just used marshmallow's load() method: Schema().load()