RESTiro

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