Add X-Total-Count header to the listing resources to enable pagination

[frol]

I would expect to return a lazy queryset from the resource method handler, and some smart (explicit) magic will take care of OpenAPI/Swagger documentation, offsetting and limiting the data, and setting X-Total-Count header to the response.

There are a few solutions I have in mind, but none of them is perfect to me:

• Wrap the @api.response() decorator, so we have the input parameters available, the original response, and the control over serialization:

  @api.route('/my_resources/')
  class MyResources(Resource):
      @parameters.MyParametersInheritedFromPaginationParameters().paginate(
          api.response(schemas.MySchema)
      )
      def get(self, args):
           return models.MyResource.query.all()

  or

  @api.route('/my_resources/')
  class MyResources(Resource):
      @api.parameters(parameters.MyParametersInheritedFromPaginationParameters())
      @api.paginate(
          api.response(schemas.MySchema)
      )
      def get(self, args):
           return models.MyResource.query.all()

• Extend the @api.response decorator to have hooks before the object gets dumped with a schema (so we can limit and offset the queryset), and after the Response is generated (so we can inject the header)

References:

• http://blog.mwaysolutions.com/2014/06/05/10-best-practices-for-better-restful-api/ (search for "Paging" section)
• http://stackoverflow.com/a/32417513/1178806

P.S. To document the headers in Swagger.json, we need the latest master of flask-restplus (the latest 0.10.1 release doesn't include the fix for noirbizarre/flask-restplus#119).