Python 3 support

[revmischa]

Fixes parsing of AST and return jsonify() function call detection.
Support schema references via API schema_class property.
Get pydoc with __doc__
setup.py

[iartarisi]

Hi @revmischa

Thanks for the PR. I think it would be a lot easier to review if the different issues were in separate PRs rather than all-in-one.

One thing I'm particularly confused about is the introduction of the new triple dash separator for a yaml endpoint description. My aim with the project was to find a way to generate a swagger schema without requiring any DSL/project-specific syntax. Anyway, I haven't run the code yet, but it looks like, after splitting out the yaml from the description, the yaml is thrown away when get_docs gets called on line 252?

Any chance of fixing (+ maybe extending) the tests and extending the existing documentation to cover the new schema_class bit and the error responses? I'm not super clear on how that part works tbh.

[revmischa]

@mapleoin thanks for your reply. All good questions.
The triple-dash yaml thing is to inline more doc info. Parameters, schema refs, response info. If you know a better way to do this I'd love to hear it. Yes you're right about the YAML being thrown away currently; I do have a test for it in my codebase but I need to merge stuff from it and update the tests for sure. I should probably have mentioned this is still a work in progress and I was more interested in preliminary feedback. It's not ready to merge yet.
I use Marshmallow and was going to check out the Marshmallow plugin, so maybe that's another option?

example YAML:

        ---
        parameters:
          - in: body
            name: content_type
            description: 'Content-type'
            type: string
            required: true
        responses:
          200:
            description: S3 upload API response...
            schema:
              type: array
              items:
                $ref: '#/definitions/S3UploadResponse'

[revmischa]

See also:
https://github.com/hobbeswalsh/flask-sillywalk
https://github.com/marshmallow-code/apispec
https://github.com/gangverk/flask-swagger

These all use YAML for marking up method docs

[revmischa]

I like https://github.com/jmcarp/flask-apispec more

[iartarisi]

Before I started this project, I looked at projects that require you to use their own schema language so they can generate a swagger spec. What I want to do here is the opposite. This project is all about removing the duplication between maintaining an API schema in parallel with the API code, regardless of whether that's in a docstring or not.

HTTP verbs and arguments lists can be gotten from the method definitions and I'm looking at ways to inspect the return values of functions so that a responses specification can also be generated.

[revmischa]

I think getting flask_classful to work with flask_apispec and marshmallow would be cool. I'm trying to figure out how to make that work.