restiro 0.19.1

Description:

restiro 0.19.1

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


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]



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)



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
)



Run tests


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