restful api文档生成器

restiro的Python项目详细描述


restiro

Build StatusCoverage Status

restful api文档生成器(内联文档+测试)

功能

  • [X]内联文档分析器
  • [X]记录器中间件示例
  • [X]以降价方式生成文档
  • [X]用HTML生成文档 [restiro-spa-material]

安装

    pip install restiro

用法

  1. 在备注中描述请求,例如:

    控制器/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]
  2. restiro中间件附加到wsgi/http验证器 (当前支持webtest),例如:

    您的项目测试初始值设定项:

    fromrestiro.middlewares.webtestimportTestAppfromrestiroimportclean_examples_dirfrommy_projectimportwsgi_appclean_examples_dir()test_app=TestApp(wsgi_app)
  3. 定义要捕获的响应,例如:

    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)
  4. 运行测试

  5. 生成文档

    $ 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

欢迎加入QQ群-->: 979659372 Python中文网_新手群

推荐PyPI第三方库


热门话题
如何使用运行时从JAVA运行openssl命令?   不使用线程安全类(如AtomicInteger和SynchronizedList)的java ProducerConsumer问题   匹配字符串的java模式   在java中使用泛型接口作为返回类型   java将可能具有序列化JSON值的hashmap作为节点添加到JSON字符串中   Eclipse无法从Java8流推断正确的类型   java无法了解标准JButton的大小   java我能用一个循环优化这个函数吗(在第一种方法中)?   Apache CXF中基于WebSocket的java SOAP?   java想要运行奇偶和求和三步   矩阵上随机元素的java集值   java布尔相等:0==a,操作数顺序重要吗?   java Eclipse不会退出我的插件   java如何在spring的SOAP拦截器中获取HttpServletRequest和HttpServletResponse