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

Я работаю над API (используя фреймворк Python Bottle), который будет использоваться множеством клиентов. Поступая так, я пытаюсь убить двух зайцев одним выстрелом в отношении документации. Что я хотел бы сделать, так это создать какой-то тип декоратора / атрибута, в котором я могу описать каждый общедоступный маршрут 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

Есть предложения о том, как реализовать этот подход? Существует ли что-то подобное, о чем я не знаю?


python asp.net-web-api documentation bottle
person user163757    schedule 08.01.2015    source источник

Ответы (1)


arrow_upward
2
arrow_downward

Я бы использовал обычные строки документации и создал шаблон, чтобы отображать ваши документы 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

person Joran Beasley    schedule 08.01.2015