Flask'ta yazılmış bir REST API'sı için dokümantasyonu otomatik olarak üretmek için hangi araçlar kullanılabilir?

Question

Yazdığım bir Flask REST API'sinden otomatik olarak REST API dokümanlar üretmenin hızlı bir yolunu arıyorum. Bunu yapabilecek araçları ve kodu nasıl işaretleyeceğimi bilen var mı?

Answer 1

Sana Sphinx öneriyoruz, (docs.python.org da Sphinx kullanır) Eğer __doc__ olarak belgelere ekleyin ve Sfenks'in autodoc modül sizin için dokümanlar üretecektir. İşaretleme, Markdown'a benzer reST'dur.

ör .:

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

Answer 2

bir Matara uzantısı vardır: flask-autodoc özel uç nokta rota kuralı ayrıştırma oto belgeleri için. Basit html dokümantasyon sayfasındaki böyledir

@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 

: Sen doc istediğiniz API'leri belirtmek için doc dekoratör ekleyebilir

Answer 3

Gerçekten gibi Swagger bir API elde etmelerini sağladığı için kodunuza sadece birkaç dekoratör ve yorum ekleyerek belgeler. Flask Swagger kullanılabilir.

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

Sonra sadece (otomatik statik gerekli hizmet vermektedir)/API/v1/spec ziyaret ederek bir html arayüzünde yöntem ve notlar görebilirsiniz. Ayrıca tüm API açıklamanızı JSON’a aktarabilir ve aksi halde çözümleyebilirsiniz.