README.md

Giya

An awesome REST boilerplate that uses Flask-RESTX (formerly Flask-RESTPlus). It has the usual API features to get you started and off the ground, it's also designed to be easily scalable and extendable.

I wrote this boilerplate because I found that a lot of Flask REST boilerplates are either doing too much, is lacking, or it simply doesn't fit my needs.

Features

• Full featured framework for fast, easy, and documented API with Flask-RESTX
• JSON Web Token Authentication with Flask-JWT-Extended
• Swagger Documentation (Part of Flask-RESTX).
• Unit Testing.
• Database ORM with Flask-SQLAlchemy
• Database Migrations using Flask-Migrate
• Object serialization/deserialization with Flask-Marshmallow
• Data validations with Marshmallow Marshmallow

Flask CLI help command output:

Usage: flask [OPTIONS] COMMAND [ARGS]...

  A general utility script for Flask applications.

  Provides commands from Flask, extensions, and the application. Loads the
  application defined in the FLASK_APP environment variable, or from a
  wsgi.py file. Setting the FLASK_ENV environment variable to 'development'
  will enable debug mode.

    $ export FLASK_APP=giya.py
    $ export FLASK_ENV=development
    $ flask run

Options:
  --version  Show the flask version
  --help     Show this message and exit.

Commands:
  db      Perform database migrations.
  routes  Show the routes for the app.
  run     Run a development server.
  shell   Run a shell in the app context.
  test    Run unit tests

Pre-requisites

This boilerplate uses SQLite as its database, make sure you have it installed. Pipenv is recommended to help manage the dependencies and virtualenv.

You can also use other DBs like PostGreSQL, make sure you have it setup and update your DATABASE_URL in your configs. Read more at Flask-SQLAlchemy's documentations.

It uses Black for code styling/formatting.

Usage

Notes

By default the / route is used by the auth blueprint.

The rest of the resources are found in /api (This is the docs route by default, this can be changed easily).

Note: Pipenv seems to have been becoming unmaintained or unsupported, so virtualenv is recommended to manage your packages and Python environment, hence why requirements.txt has been generated.

Installing with Pipenv

# Clone the repo
$ git clone https://github.com/X1Zeth2X/flask-restx-boilerplate.git

# Install packages with pipenv
$ pipenv install

Running

Please specify your app's environment variables in a .env file, otherwise Flask CLI wouldn't find your app.

# .env file example
export FLASK_APP=giya

# configs: production, testing, development, and default (uses DevelopmentConfig)
export FLASK_CONFIG=development

# Another way of assigning environment variables is:
FLASK_APP=giya
FLASK_CONFIG=development

# Read more at https://github.com/theskumar/python-dotenv

# Enter the virtualenv
$ pipenv shell

# (Optional for development, recommended)
$ flask db init # Initializes a new SQLite database.
$ flask db migrate # Creates the tables in the database.

# Run the app
$ flask run

Unit testing

Giya has already some unit tests written, we encourage adding more unit tests as you scale.

# Unit testing
$ flask test

# Run specific unit test(s)
$ flask test tests.test_auth_api tests.test_user_model ...