This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (pypi.python.org).
Help us improve Python packaging - Donate today!
Project Description

Flask-Restdoc is a simple tool that generates RESTful API documentation automatically from python files.

Installation

You can install Flask-Restdoc with pip.

$ pip install flask-restdoc

How-to

Step 1. Make Restdoc Instance

First, you need to make an instance of Restdoc.

from flask import Flask
from restdoc import Restdoc

app = Flask(__name__)

restdoc = Restdoc(app)

Or you can initiate app later.

restdoc.init_app(app)

Step 2. Configure Output Path

You have to set output path at app.config. Path must includes output file name.

app.config['RESTDOC_OUTPUT'] = '/Users/xoul/Documents/api.md'

Step 3. Decorate URL Endpoints

In your view.py (or something else), add decorators to url endpoints.

api = Blueprint('api', __name__)

@restdoc.api(api,
        description='asdasd',
        params=[
                ('email', True),
                ('password', True, 'SHA-1')
        ],
        status=200,
        sample_response={
                'status': 'ok'
        },
        errors=[1001,1002])
@api.route('/login')
def login():
        pass

Parameters

blueprint
A blueprint object.
description
API description string.
params
URL Parameters or form data for request. List of tuple contains parameter name, required option(True if required) and description.
status
A HTTP status code for successful request. 200 is default.
sample_response
A sample response object. This will be written in JSON format.
errors
Error codes that can be occurred in this function.

Step 4. Error Definition List (Optional)

Flask-Restdoc generates error information from error definition list. You have to make a list of error definitions. Each error object is tuple that contains HTTP status code, error code and message.

errors = [
        # (HTTP status, Error code, Message)
        (403,   1001,   'NOT_AUTHORIZED'),
        (400,   1100,   'NEED_EMAIL'),
        (400,   1101,   'NEED_PASSWORD')
]

Then, set error definition list to restdoc instance.

restdoc.set_errors(errors)

Step 5. Generate

Just call method generate to generate documentation.

restdoc.generate()

Change Logs

v0.0.2

  • Added line break after error definitions.
  • Converted <int:id> to {id} format.

v0.0.1

  • Hello, Restdoc!

Future Plans

  • Support other formats. (Such as rst, html, etc.)
  • Model documentation.

License

Flask-Restdoc is under MIT License.

Release History

Release History

0.0.2

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.0.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

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

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
Flask-Restdoc-0.0.2.tar.gz (4.6 kB) Copy SHA256 Checksum SHA256 Source Sep 28, 2013

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting