Skip to main content

RESTful API documentation generator

Project description

RESTiro

Build Status Coverage Status

RESTful API documentation generator (inline documentation + tests)

Features

  • [x] Inline documentation parser
  • [x] Example recorder middleware
  • [x] Generate documentation in Markdown
  • [x] 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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for restiro, version 0.19.1
Filename, size File type Python version Upload date Hashes
Filename, size restiro-0.19.1.tar.gz (20.5 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page