Research Best Methods for Swagger Documentation

[dankolbman]

Switching away from RESTPlus cost us the automatic swagger documentation.
There is still a couple tools to make documentation easier with Marshmallow:

apispec
flasgger

Time box research for Flask-APIspec to no more than 4 hours. If it is not straight forward- then we need to proceed with manual documentation for MVP - which would require a ticket for each resource ~2 pts each.

[znatty22]

Been playing around with flask-apispec for an hour or so but its not looking too good right now. Trying to follow basic usage instructions according to docs but I'm having a problem getting it to work with our blueprint. Might be something I'm doing wrong but I'm not sure yet.

Even though I haven't put too much time into this, I'm heavily leaning towards not using an auto-doc library right now and going with manual swagger docs. Also, there does seem to be a couple open issues/PRs that may affect us in the near future (one of which @dankolbman referred to already - here)

If anyone is interested, I pushed what I have so far to this branch

[dankolbman]

Yah, see issue #181 over at marshmallow-code/apispec, it's the same thing. I've been meaning to take a crack at it, but it's just not going to be that pretty the way I'm thinking of solving it now.

We can still do manual docs inside jsons in each of the resource directories, then reference them in the doc string, and compile them and join them with the apispeced mashmallow schemas to create the final swagger. It would still be almost entirely manual, but it would save us from having an enormous swagger.json that needs to be maintained.

[znatty22]

Sounds good to me. Even if I got this working and #181 was resolved, I have a feeling we will run into other headaches down the road. flask-apispec seems cool, but it looks like its too young.