Skip to main content

RESTful API documentation generator

Project description

# RESTiro

[![Build Status](
https://travis-ci.org/meyt/restiro.svg?branch=master
)](
https://travis-ci.org/meyt/restiro
)
[![Coverage Status](
https://coveralls.io/repos/github/meyt/restiro/badge.svg?branch=master
)](
https://coveralls.io/github/meyt/restiro?branch=master
)

RESTful API documentation generator (inline documentation + tests)


## Features

- [x] Inline documentation parser
- [x] Example recorder middleware
- [x] Generate documentation in Markdown
- [ ] Generate documentation in HTML
- [ ] Try-it on browser

## Install

```
pip install restiro
```

## Usage

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

controller/shelf.py
```python
class ShelfController:

def post(self):
"""
@api {post} /shelf/:shelfId/book Add book into shelf

@apiVersion 1
@apiGroup Book
@apiPermission None

@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:

```python
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:

```python

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
```markdown
# 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}] [-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}, --generator {markdown,json,spa_material}
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.

Source Distribution

restiro-0.8.0.tar.gz (18.4 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page