Skip to main content

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

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.

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 Flask-Restdoc, version 0.0.2
Filename, size File type Python version Upload date Hashes
Filename, size Flask-Restdoc-0.0.2.tar.gz (4.6 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 SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page