Документирование API бутылки Python с пользовательскими декораторами/атрибутами

Question

Я работаю над API (с использованием инфраструктуры Python Bottle), который будет использоваться различными клиентами. При этом я пытаюсь убить 2 птиц одним камнем относительно документации. То, что я хотел бы сделать, это создать некоторый тип декоратора/атрибута, где я могу описать каждый публичный маршрут API. Затем у меня есть маршрут, который пересекает все другие маршруты и собирает эту информацию (описание, ввод, вывод ...). Эта информация возвращается как массив JSON, где она отображается в удобном для пользователя формате html.

Сбор информации о маршруте легко:

@route('/api-map',method=['GET']) 
def api_map(): 
    api_methods = [] 
    for route in app.routes: 
     if route.rule != "/api-map": 
      ##TODO: get custom attribute from routes function with description, inputs, outputs... 
      api_methods.append({"route":route.rule,"desc":"?"}) 

    response.content_type = 'application/json' 
    return {"apiMap":api_methods} 

Но я застрял на том, как достичь документации. Ниже концептуально, что я пытаюсь стянуть, где «svmdoc» является атрибутом, где я помещал эту информацию:

@route('/token',method=['GET']) 
@svmdoc(desc="Generates Token",input="username and password") 
def getToken(): 
    #TODO token magic 

Любые предложения о том, как реализовать этот подход? Что-то вроде этого уже существует, о котором я не знаю?

Answer 1

Я хотел бы использовать нормальные и строки документации создать шаблон, чтобы сделать ваш API документы в читаемом образом

bottle0_template.tpl

<table> 
<tr style="background-color:#CCCFDF"><th colspan="2">API Documentation</th></tr> 
<tr style="background-color:#CCCFDF"><th>ENDPOINT</th><th>DESC</th></tr> 
% for color,resource in zip(colors,routes) : 
    % docx = resource.callback.__doc__.replace("\n","<br/>") 
    <tr style="background-color:{{ color }}"><td>{{ resource.rule }}</td><td> {{! docx }} </td></tr> 
% end 
</table> 

затем измените файл

bottle0. py

from bottle import route, run,app,template 
from itertools import cycle 
docs_exclude = "/api-doc","/api-map" 

@route('/api-doc',method=['GET']) 
def api_doc(): 
    colors = cycle('#FFFFFF #CCCFDF'.split()) 
    routes = filter(lambda x:x.rule not in docs_exclude,app[0].routes) 
    return template("bottle0_template",colors=colors,routes=routes) 


@route('/token') 
def token(): 
    ''' 
    grant api token 

    params: 
     username: string,username of user 
     password: string, password of user 
    ''' 
    return "ASD!@#!#!@#" 

@route('/userinfo') 
def userinfo(): 
    ''' 
    grant api token 

    params: 
     - username: string,username of user to retrieve data for 
     - code: string, api access token 
    ''' 
    return json.dumps({"name":"bob"}) 

#print app[0].routes[1].callback.__doc__#api-doc 
run(host='localhost', port=8080, debug=True) 

затем перейдите по ссылке http://localhost:8080/api-doc