Flaskで書かれたREST APIのドキュメントを自動生成するためのツールはありますか？

Question

私が書いたFlask REST APIからREST APIドキュメントを自動生成するための素早い方法を探しています。誰もがこれを行うことができ、私はどのようにコードをマークアップするツールを知っていますか？

Answer 1

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

例えば：

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

Answer 2

フラスコの拡張があります：flask-autodoc特別にエンドポイントのルートルールを解析し、自動ドキュメントについて。単純なHTMLドキュメントのページはこのようなものです

@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 

：あなたはドキュメントしたいAPIを指定するには、docデコレータを追加することができます

Answer 3

私は本当にのような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 /スペックを訪問し、HTMLインターフェイスで、あなたの方法や注意事項を確認することができます。 JSONでAPIの説明をすべて取得し、それ以外の場合は解析することもできます。