Skip to content
/ restiro Public

RESTful API documentation generator (inline documentation + tests)

License

Notifications You must be signed in to change notification settings

meyt/restiro

Repository files navigation

RESTiro

Build Status Coverage Status

RESTful API documentation generator (inline documentation + tests)

Features

  • Inline documentation parser
  • Example recorder middleware
  • Generate documentation in Markdown
  • Generate documentation in HTML [restiro-spa-material]

Install

    pip install restiro

Usage

  1. Describe the request in comments, e.g:

    controller/shelf.py

    class ShelfController:
        
        def post(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. Attach restiro middleware to your WSGI/HTTP verifier (currently webtest supported), e.g:

    Your project tests initializer:

    from restiro.middlewares.webtest import TestApp
    from restiro import clean_examples_dir
    
    from my_project import wsgi_app
    
    clean_examples_dir()
    test_app = TestApp(wsgi_app)
  3. Define responses to capture, e.g:

    def test_shelf(test_app):
        test_app.get('/shelf/100/book')
        
        test_app.delete('/shelf/121/book')
        
        test_app.doc = True
        test_app.post(
            '/shelf/100/book',
            json={
                'title': 'Harry Potter',
                'author': 'JK. Rowling'
            }
        )
        
        test_app.doc = True
        test_app.post(
            '/shelf/100/book',
            json={
                'title': 'Harry Potter2'
            },
            status=400
        )
  4. Run tests

  5. Build documentation

    $ restiro a_library
    

    Response will be something like:

    shelf-{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