restful api文档生成器
restiro的Python项目详细描述
restiro
restful api文档生成器(内联文档+测试)
功能
- [X]内联文档分析器
- [X]记录器中间件示例
- [X]以降价方式生成文档
- [X]用HTML生成文档 [restiro-spa-material]
安装
pip install restiro
用法
在备注中描述请求,例如:
控制器/shelf.py
classShelfController:defpost(self):""" @api {post} /shelf/:shelfId/book Add book into shelf @apiVersion 1 @apiGroup Book @apiPermission Noneres @apiParam {String} title @apiParam {String} author @apiParam {DateTime} [publishDate] @apiDescription Here is some description with full support of markdown. - watch this! - and this! - there is a list! """return[11,22,33]
将
restiro
中间件附加到wsgi/http验证器 (当前支持webtest
),例如:您的项目测试初始值设定项:
fromrestiro.middlewares.webtestimportTestAppfromrestiroimportclean_examples_dirfrommy_projectimportwsgi_appclean_examples_dir()test_app=TestApp(wsgi_app)
定义要捕获的响应,例如:
deftest_shelf(test_app):test_app.get('/shelf/100/book')test_app.delete('/shelf/121/book')test_app.doc=Truetest_app.post('/shelf/100/book',json={'title':'Harry Potter','author':'JK. Rowling'})test_app.doc=Truetest_app.post('/shelf/100/book',json={'title':'Harry Potter2'},status=400)
运行测试
生成文档
$ restiro a_library
回答如下:
书架-{shelf_id}-book-post.md
# Add book into shelf ## `POST` `/shelf/:shelfId/book` Here is some description with full support of markdown. - watch this! - and this! - there is a list! ## Parameters ### Form parameters Name | Type | Required | Default | Example | enum | Pattern | MinLength | MaxLength | Minimum | Maximum | Repeat | Description --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- title | String | `True` | | | | | | | | | `False` | author | String | `True` | | | | | | | | | `False` | publishDate | DateTime | `False` | | | | | | | | | `False` | ## Examples ### 200 OK #### Request: ``` POST /shelf/100/book Content-Type: application/x-www-form-urlencoded ``` ``` title=Harry Potter author=JK. Rowling ``` #### Response: ``` Content-Type: application/json ``` ``` [11, 22, 33] ``` ### 400 Bad Request, missed parameter `author` #### Request: ``` POST /shelf/100/book Content-Type: application/x-www-form-urlencoded ``` ``` title=Harry Potter2 ``` #### Response: ``` Content-Type: application/json ``` ``` {"message": "Missed parameter `author`"} ``` ---
cli
usage: restiro [-h] [-t TITLE] [-o OUTPUT] [-b BASE_URI]
[-g {markdown,json,spa_material,mock}] [-l LOCALES]
[--build-gettext [BUILD_GETTEXT]]
src
Restiro Builder
positional arguments:
src Project module name
optional arguments:
-h, --help show this help message and exit
-t TITLE, --title TITLE
Project title
-o OUTPUT, --output OUTPUT
Output directory
-b BASE_URI, --base-uri BASE_URI
Base URI
-g {markdown,json,spa_material,mock}, --generator {markdown,json,spa_material,mock}
Generator, default: markdown
-l LOCALES, --locales LOCALES
Locales directory
--build-gettext [BUILD_GETTEXT]
Build .POT templates