A lightweight Python WebAPI's documents and tests framework based on __doc__, VanillaJS-AJAX and Flask, but not limited to Flask.
Project description
APIDocTest
A lightweight Python WebAPI's documents and tests framework based on __doc__
, VanillaJS-AJAX and Flask, but not limited to Flask.
Details
Each of API handlers' __doc__
line which starts with "@" will be treated as API's notes, excludes the leading spaces.
The "::" is the separator between key and value of each APIs='s note.
blanks in both ends of key and value are ignored.
key | value(samples) | comments |
---|---|---|
@path-parameters | variablex=literalx & variabley=literaly & variablez=literalz | placeholders in router's url, such as "/path/to//status". |
@request-parameters | variablex=literalx & variabley=literaly & variablez=literalz | like things after "?" in url, such as "http://nagexiucai.com/topic.php?title=ml-in-ten-pictures&md=ml-in-ten-pictures". |
@request-headers | content-type:text/json;charset=utf-8 & user-agent:mozilla/5.0 gecko/20100101 firefox/38.0 | |
@request-body | {"author":"bob-nx"} | |
@response-headers | content-type:text/html;charset=utf-8 & server:werkzeug/0.14.1 python/2.7.5 | |
@response-body | "hi" | |
@norm | ==[caseignored] or ~=[regular expression] or ## |
"==" for "same", "~=" for "similar", "##" for "silent"; if "[extra]" supplied, "extra" works. |
Examples
The core is use APIDocTest('router', ['methods'], name='name', description='description' version="version")
as handlers' first decorator.
from flask import blueprints
from apidoctest import APIDocTest
bapidoctest = blueprints.Blueprint("apidoctest", __name__)
@bapidoctest.route("/fuck", methods=["GET", "POST"])
@APIDocTest("/fuck", ["GET", "POST"], name="fuck", description="uncourteous.")
def Fuck():
'''
@path-parameters::
@request-parameters::
@request-headers:: Content-Type:application/json
@request-body:: {"who":"unknown"}
@response-headers:: Content-Type:text/html;charset=utf-8
@response-body:: "fuck"
@norm:: ==
'''
return "fuck"
import sys
reload(sys)
sys.setdefaultencoding("utf8")
from flask import Flask, request, render_template_string, json
from apidoctest import APIDocTestTemplateString
serv = Flask("APIDocTestDemo")
@serv.route("/apidoctest")
def documents():
return render_template_string(APIDocTestTemplateString, data=json.dumps(APIDocTest.apidocs, encoding="utf-8"))
serv.register_blueprint(bapidoctest, url_prefix="/what")
serv.run(debug=False, host="localhost", port=9527)
Result
Use browser(Google Chrome recommended), access http://localhost:9527/apidoctest
(in examples above).
- 2xx: black
- 3xx: orange
- 4xx: blue
- 5xx: red
ToDo
- I18n(Chinese friendly now)
- Parameters validation
- Input/Output grouped by test cases
- Input/Output type adaption
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for APIDocTest-0.0.3-py2-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4873fdeb2c108b69c96208ff6f172d653b6102732fc46b5059a524b40996901c |
|
MD5 | 487ff3518c49ee48d8988e7002757bef |
|
BLAKE2b-256 | 503943fcdc7ff8f1ac88c3a48c4ce4e1695214f84dbb6f7485ec113ac14e1675 |