web-dev-qa-db-ja.com

REST Flaskで記述されたAPIのドキュメントを自動生成するために使用できるツールは何ですか？

自動生成する簡単な方法を探していますRESTからのAPIドキュメントFlask REST私が書いたAPI 。これを実行できるツールと、コードをマークアップする方法を知っている人はいますか？

pythonrestdocumentationflask
29
Martin Charlesworth

Sphinx をお勧めします。ドキュメントを__doc__として追加すると、Sphinxのautodocモジュールがドキュメントを生成します（ docs.python.org もSphinxを使用しています）。マークアップは reStructuredText であり、Markdownに似ています（Markdownを使用する場合は pdoc を使用できます）。

例えば。：

@app.route('/download/<int:id>')
def download_id(id):
    '''This downloads a certain image specified by *id*'''
    return ...
20
dav1d

私は本当に Swagger が好きです。コードにいくつかのデコレータとコメントを追加するだけでAPIドキュメントを生成できるからです。 Flask Swagger が利用可能です。

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):
...

次に、/ api/v1/specにアクセスするだけで、メソッドとメモをHTMLインターフェースで確認できます（必要なstaticを自動的に提供します）。 JSONですべてのAPI記述を取得し、それ以外の場合は解析することもできます。

17
Clément Renaud

Flask拡張子： flask-autodoc があり、エンドポイントルートルールを特別に解析する自動ドキュメンテーションがあります。docデコレータを追加して、必要なAPIを指定できますドキュメントへ：

@app.route('/doc')
@auto.doc()
def documentation():
    '''
    return API documentation page
    '''
    return auto.html()

@app.route('/')
@auto.doc()
def welcome():
    '''
    Welcome API
    '''
    commit_hash = subprocess.check_output(["git", "rev-parse", "HEAD"])
    commit_msg = subprocess.check_output(["git", "log", "-1", "--format=%s"])
    date_time = subprocess.check_output(["git", "log", "-1", "--format=%cd"])
    return "Welcome to VM Service Server. <br/>" \
           "The last commit: %s<br/>Date: %s, <br>Hash: %s" % \
           (commit_msg, date_time, commit_hash), 200

シンプルなhtmlドキュメントページは次のとおりです。

enter image description here

6
Cody