I'm looking for a quick way to auto produce REST API docs from a Flask REST API I've written. Does anyone know of tools that can do this and how I would markup the code?
I would recommend you Sphinx, you add your documentation as
__doc__ and the
autodoc module of Sphinx will generate the docs for you (docs.python.org also uses Sphinx). The markup is reStructuredText, similiar to Markdown (if you prefer Markdown, you can use pdoc).
@app.route('/download/<int:id>') def download_id(id): '''This downloads a certain image specified by *id*''' return ...
from flask import Flask from flask.ext.restful import Api from flask_restful_swagger import swagger app = Flask(__name__) api = swagger.docs(Api(app), apiVersion='1', api_spec_url="/api/v1/spec") class Unicorn(Resource): "Describing unicorns" @swagger.operation( notes='some really good notes' ) def get(self, todo_id): ...
Then you can see your methods and notes in an html interface just by visiting /api/v1/spec (it serves needed static automatically). You can also just get all your API description in JSON and parse it otherwise.