{"id":13595424,"url":"https://github.com/karec/cookiecutter-flask-restful","last_synced_at":"2026-01-16T05:57:38.234Z","repository":{"id":37549664,"uuid":"64237129","full_name":"karec/cookiecutter-flask-restful","owner":"karec","description":"Flask cookiecutter template for builing APIs with flask-restful, including JWT auth, cli, tests, swagger, docker and more","archived":false,"fork":false,"pushed_at":"2023-04-27T20:35:17.000Z","size":155,"stargazers_count":796,"open_issues_count":12,"forks_count":183,"subscribers_count":17,"default_branch":"master","last_synced_at":"2024-11-06T18:43:58.333Z","etag":null,"topics":["cookiecutter","flask","flask-restful","jwt","marshmallow"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/karec.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2016-07-26T16:29:49.000Z","updated_at":"2024-11-06T09:03:59.000Z","dependencies_parsed_at":"2024-01-16T22:18:25.574Z","dependency_job_id":"edcd11c9-8bc9-4054-9a83-43b16b171ed6","html_url":"https://github.com/karec/cookiecutter-flask-restful","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karec%2Fcookiecutter-flask-restful","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karec%2Fcookiecutter-flask-restful/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karec%2Fcookiecutter-flask-restful/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karec%2Fcookiecutter-flask-restful/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/karec","download_url":"https://codeload.github.com/karec/cookiecutter-flask-restful/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248049334,"owners_count":21039204,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cookiecutter","flask","flask-restful","jwt","marshmallow"],"created_at":"2024-08-01T16:01:49.742Z","updated_at":"2026-01-16T05:57:38.192Z","avatar_url":"https://github.com/karec.png","language":"Python","funding_links":[],"categories":["HarmonyOS","Python"],"sub_categories":["Windows Manager"],"readme":"# cookiecutter-flask-restful\n\nCookiecutter template for flask restful, including blueprints, application factory, and more\n\n[![Build Status](https://travis-ci.org/karec/cookiecutter-flask-restful.svg?branch=master)](https://travis-ci.org/karec/cookiecutter-flask-restful)\n\n## Introduction\n\nThis cookie cutter is a very simple boilerplate for starting a REST api using Flask, flask-restful, marshmallow, SQLAlchemy and jwt.\nIt comes with basic project structure and configuration, including blueprints, application factory and basics unit tests.\n\nFeatures\n\n* Simple flask application using application factory, blueprints\n* [Flask command line interface](http://flask.pocoo.org/docs/1.0/cli/) integration\n* Simple cli implementation with basics commands (init, run, etc.)\n* [Flask Migrate](https://flask-migrate.readthedocs.io/en/latest/) included in entry point\n* Authentication using [Flask-JWT-Extended](http://flask-jwt-extended.readthedocs.io/en/latest/) including access token and refresh token management\n* Simple pagination utils\n* Unit tests using pytest and factoryboy\n* Configuration using environment variables\n* OpenAPI json file and swagger UI\n\nUsed packages :\n\n* [Flask](http://flask.pocoo.org/)\n* [Flask-RESTful](https://flask-restful.readthedocs.io/en/latest/)\n* [Flask-Migrate](https://flask-migrate.readthedocs.io/en/latest/)\n* [Flask-SQLAlchemy](http://flask-sqlalchemy.pocoo.org/2.3/)\n* [Flask-Marshmallow](https://flask-marshmallow.readthedocs.io/en/latest/)\n* [Flask-JWT-Extended](http://flask-jwt-extended.readthedocs.io/en/latest/)\n* [marshmallow-sqlalchemy](https://marshmallow-sqlalchemy.readthedocs.io/en/latest/)\n* [passlib](https://passlib.readthedocs.io/en/stable/)\n* [tox](https://tox.readthedocs.io/en/latest/)\n* [pytest](https://docs.pytest.org/en/latest/)\n* [factoryboy](http://factoryboy.readthedocs.io/en/latest/)\n* [dotenv](https://github.com/theskumar/python-dotenv)\n* [apispec](https://github.com/marshmallow-code/apispec)\n\n\n## Usage\n\n* [Installation](#installation)\n* [Configuration](#configuration)\n* [Authentication](#athentication)\n* [Running tests](#running-tests)\n* [WSGI Server](#installing-a-wsgi-server)\n* [Flask CLI](#using-flask-cli)\n* [Using Celery](#using-celery)\n* [Using Docker](#using-docker)\n* [Makefile](#makefile-usage)\n* [APISpec, swagger, and redoc](#using-apispec-swagger-and-redoc)\n* [Changelog](#changelog)\n\n\n### Installation\n\n#### Install cookiecutter\n\nMake sure you have cookiecutter installed in your local machine.\n\nYou can install it using this command : `pip install cookiecutter`\n\n#### Create your project\n\nStarting a new project is as easy as running this command at the command line. No need to create a directory first, the cookiecutter will do it for you.\n\nTo create a project run the following command and follow the prompt\n\n`cookiecutter https://github.com/karec/cookiecutter-flask-restful`\n\n#### Install project requirements\n\nLet's say you named your app `myapi` and your project `myproject`\n\nYou can install it using pip :\n\n```\ncd myproject\npip install -r requirements.txt\npip install -e .\n```\n\nYou now have access to cli commands and can init your project\n\n```\nflask db init\nflask db migrate\nflask db upgrade\nflask init  # creates admin user\n```\n\nTo list all commands\n\n```\nflask --help\n```\n\n### Configuration\n\nConfiguration is handled by environment variables, for development purpose you just\nneed to update / add entries in `.flaskenv` file.\n\nIt's filled by default with following content:\n\n```\nFLASK_ENV=development\nFLASK_APP=\"myapp.app:create_app\"\nSECRET_KEY=changeme\nDATABASE_URI=\"sqlite:///myapp.db\"\nCELERY_BROKER_URL=amqp://guest:guest@localhost/  # only present when celery is enabled\nCELERY_RESULT_BACKEND_URL=amqp://guest:guest@localhost/  # only present when celery is enabled\n```\n\nAvaible configuration keys:\n\n* `FLASK_ENV`: flask configuration key, enables `DEBUG` if set to `development`\n* `SECREY_KEY`: your application secret key\n* `DATABASE_URI`: SQLAlchemy connection string\n* `CELERY_BROKER_URL`: URL to use for celery broker, only when you enabled celery\n* `CELERY_RESULT_BACKEND_URL`: URL to use for celery result backend (e.g: `redis://localhost`)\n\n### Authentication\n\n\nTo access protected resources, you will need an access token. You can generate \nan access and a refresh token using `/auth/login` endpoint, example using curl\n\n```bash\ncurl -X POST -H \"Content-Type: application/json\" -d '{\"username\": \"admin\", \"password\": \"admin\"}' http://localhost:5000/auth/login\n```\n\nThis will return something like this\n\n```json\n{\n  \"access_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiYWNjZXNzIiwiaWRlbnRpdHkiOjEsImlhdCI6MTUxMDAwMDQ0MSwiZnJlc2giOmZhbHNlLCJqdGkiOiI2OTg0MjZiYi00ZjJjLTQ5MWItYjE5YS0zZTEzYjU3MzFhMTYiLCJuYmYiOjE1MTAwMDA0NDEsImV4cCI6MTUxMDAwMTM0MX0.P-USaEIs35CSVKyEow5UeXWzTQTrrPS_YjVsltqi7N4\", \n  \"refresh_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZGVudGl0eSI6MSwiaWF0IjoxNTEwMDAwNDQxLCJ0eXBlIjoicmVmcmVzaCIsImp0aSI6IjRmMjgxOTQxLTlmMWYtNGNiNi05YmI1LWI1ZjZhMjRjMmU0ZSIsIm5iZiI6MTUxMDAwMDQ0MSwiZXhwIjoxNTEyNTkyNDQxfQ.SJPsFPgWpZqZpHTc4L5lG_4aEKXVVpLLSW1LO7g4iU0\"\n}\n```\nYou can use access_token to access protected endpoints :\n\n```bash\ncurl -X GET -H \"Content-Type: application/json\" -H \"Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiYWNjZXNzIiwiaWRlbnRpdHkiOjEsImlhdCI6MTUxMDAwMDQ0MSwiZnJlc2giOmZhbHNlLCJqdGkiOiI2OTg0MjZiYi00ZjJjLTQ5MWItYjE5YS0zZTEzYjU3MzFhMTYiLCJuYmYiOjE1MTAwMDA0NDEsImV4cCI6MTUxMDAwMTM0MX0.P-USaEIs35CSVKyEow5UeXWzTQTrrPS_YjVsltqi7N4\" http://127.0.0.1:5000/api/v1/users\n```\n\nYou can use refresh token to retreive a new access_token using the endpoint `/auth/refresh`\n\n\n```bash\ncurl -X POST -H \"Content-Type: application/json\" -H \"Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZGVudGl0eSI6MSwiaWF0IjoxNTEwMDAwNDQxLCJ0eXBlIjoicmVmcmVzaCIsImp0aSI6IjRmMjgxOTQxLTlmMWYtNGNiNi05YmI1LWI1ZjZhMjRjMmU0ZSIsIm5iZiI6MTUxMDAwMDQ0MSwiZXhwIjoxNTEyNTkyNDQxfQ.SJPsFPgWpZqZpHTc4L5lG_4aEKXVVpLLSW1LO7g4iU0\" http://127.0.0.1:5000/auth/refresh\n```\n\nThis will only return a new access token\n\n```json\n{\n  \"access_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiYWNjZXNzIiwiaWRlbnRpdHkiOjEsImlhdCI6MTUxMDAwMDYxOCwiZnJlc2giOmZhbHNlLCJqdGkiOiIzODcxMzg4Ni0zNGJjLTRhOWQtYmFlYS04MmZiNmQwZjEyNjAiLCJuYmYiOjE1MTAwMDA2MTgsImV4cCI6MTUxMDAwMTUxOH0.cHuNf-GxVFJnUZ_k9ycoMMb-zvZ10Y4qbrW8WkXdlpw\"\n}\n```\n\n### Running tests\n\n\n#### Using tox\n\nSimplest way to run tests is to use tox, it will create a virtualenv for tests, install all dependencies and run pytest\n\n```\ntox\n```\n\nIf you just want to run pytest and avoid linters you can use \n\n```\ntox -e test\n```\n\n#### Using pytest directly\n\nIf you want to run pytest manually without using tox you'll need to install some dependencies before\n\n```\npip install pytest pytest-runner pytest-flask pytest-factoryboy pytest-celery factory_boy\n```\n\nThen you can invoke pytest\n\n```\npytest\n```\n\nNote that tox is setting environment variables for you when testing, but when using pytest directly that's not the case. To avoid setting up env variables each time you run pytest, this cookiecutter provide a `.testenv` file that contains default configuration for testing. Don't forget to update it if your local env doesn't match those defaults.\n\n#### Using docker\n\nTesting with docker is another great option, since it take cares of everything and spawn required services for you. To run tests within docker containers, you can use the provided Makefile:\n\nBuild images:\n\n```bash\nmake build\n```\n\nRunning tox with flake8, black and pytest:\n\n```bash\nmake tox\n```\n\nRunning tox with pytest only:\n\n```bash\nmake test\n```\n\n#### Testing Celery\n\nTesting celery require at least a rabbitMQ (or any other compatible broker) running. By default, when you use tox or the `.testenv` file, celery broker and result backend are configured as follow:\n\n```\nCELERY_BROKER_URL=amqp://guest:guest@localhost/\nCELERY_RESULT_BACKEND_URL=amqp://guest:guest@localhost/\n```\n\nMeaning that it will try to connect to a local rabbitMQ server using guest user. Don't forget to update those settings if your configuration doesn't match.\n\nIf you can't / don't want to install a local rabbitMQ server or any other available celery broker, you have 2 options:\n\n1. Use docker\n\nYou can use docker-compose to run tests, as it will spawn a rabbitMQ and a redis servera and set correct env variables for configuration. All tests commands are available inside the Makefile to simplify this process.\n\n2. Update the tests to use eager mode\n\n**NOTE** this is not recommanded by celery: https://docs.celeryproject.org/en/stable/userguide/testing.html\n\nAlternatively, if you don't have a local broker and can't use docker, you can update unit tests to run them using the `task_always_eager` celery setting. This will actually run all tasks locally by blocking until tasks return (see https://docs.celeryproject.org/en/stable/userguide/configuration.html#std:setting-task_always_eager for more details).\n\nExample of `test_celery.py` file that use `task_always_eager`\n\n```python\nimport pytest\n\nfrom myapi.app import init_celery\nfrom myapi.tasks.example import dummy_task\n\n\n@pytest.fixture(scope=\"session\")\ndef celery_session_app(celery_session_app, app):\n    celery = init_celery(app)\n\n    celery_session_app.conf = celery.conf\n    celery_session_app.conf.task_always_eager = True\n    celery_session_app.Task = celery_session_app.Task\n\n    yield celery_session_app\n\n\ndef test_example(celery_session_app):\n    \"\"\"Simply test our dummy task using celery\"\"\"\n    res = dummy_task.delay()\n    assert res.get() == \"OK\"\n```\n\n### Installing a wsgi server\n#### Running with gunicorn\n\nThis project provide a simple wsgi entry point to run gunicorn or uwsgi for example.\n\nFor gunicorn you only need to run the following commands\n\n```\npip install gunicorn\ngunicorn myapi.wsgi:app\n```\n\nAnd that's it ! Gunicorn is running on port 8000\n\nIf you chose gunicorn as your wsgi server, the proper commands should be in your docker-compose file.\n\n#### Running with uwsgi\n\nPretty much the same as gunicorn here\n\n```\npip install uwsgi\nuwsgi --http 127.0.0.1:5000 --module myapi.wsgi:app\n```\n\nAnd that's it ! Uwsgi is running on port 5000\n\nIf you chose uwsgi as your wsgi server, the proper commands should be in your docker-compose file.\n\n### Using Flask CLI\n\nThis cookiecutter is fully compatible with default flask CLI and use a `.flaskenv` file to set correct env variables to bind the application factory.\nNote that we also set `FLASK_ENV` to `development` to enable debugger.\n\n\n### Using Celery\n\nThis cookiecutter has an optional [Celery](http://www.celeryproject.org/) integration that let you choose if you want to use it or not in your project.\nIf you choose to use Celery, additionnal code and files will be generated to get started with it.\n\nThis code will include a dummy task located in `yourproject/yourapp/tasks/example.py` that only return `\"OK\"` and a `celery_app` file used to your celery workers.\n\n\n#### Running celery workers\n\nIn your project path, once dependencies are installed, you can just run\n\n```\ncelery -A myapi.celery_app:app worker --loglevel=info\n```\n\nIf you have updated your configuration for broker / result backend your workers should start and you should see the example task avaible\n\n```\n[tasks]\n  . myapi.tasks.example.dummy_task\n```\n\n\n#### Running a task\n\nTo run a task you can either import it and call it\n\n```python\n\u003e\u003e\u003e from myapi.tasks.example import dummy_task\n\u003e\u003e\u003e result = dummy_task.delay()\n\u003e\u003e\u003e result.get()\n'OK'\n```\n\nOr use the celery extension\n\n```python\n\u003e\u003e\u003e from myapi.extensions import celery\n\u003e\u003e\u003e celery.send_task('myapi.tasks.example.dummy_task').get()\n'OK'\n```\n\n## Using docker\n\n**WARNING** both Dockerfile and `docker-compose.yml` are **NOT** suited for production, use them for development only or as a starting point.\n\nThis template offer simple docker support to help you get started and it comes with both Dockerfile and a `docker-compose.yml`. Please note that docker-compose is mostly useful when using celery\nsince it takes care of running rabbitmq, redis, your web API and celery workers at the same time, but it also work if you don't use celery at all.\n\nDockerfile has intentionally no entrypoint to allow you to run any command from it (server, shell, init, celery, ...)\n\nNote that you still need to init your app on first start, even when using compose.\n\n```bash\ndocker build -t myapp .\n...\ndocker run --env-file=.flaskenv myapp init\ndocker run --env-file=.flaskenv -p 5000:5000 myapp run -h 0.0.0.0\n * Serving Flask app \"myapi.app:create_app\" (lazy loading)\n * Environment: development\n * Debug mode: on\n * Running on http://0.0.0.0:5000/ (Press CTRL+C to quit)\n * Restarting with stat\n * Debugger is active!\n * Debugger PIN: 214-619-010\n```\n\nWith compose\n\n```bash\ndocker-compose up\n...\ndocker exec -it \u003ccontainer_id\u003e flask init\n```\n\nWith docker-compose and the Makefile\n```bash\nmake init\n```\n\n## Makefile usage\n\nInitizalize the environment\n```bash\nmake init\n```\n\nBuild the containers\n```bash\nmake build\n```\n\nRun the containers\n```bash\nmake run\n```\n\nCreate migrations folder and database\n```bash\nmake db-init\n```\n\nCreate new database migration\n```bash\nmake db-migrate\n```\n\nApply database migrations\n```bash\nmake db-upgrade\n```\n\nRun tests inside containers\n```bash\nmake test\n```\n\n## Using APISpec, Swagger, and ReDoc\n\nThis boilerplate comes with pre-configured APISpec and swagger endpoints. Using default configuration you have four endpoints available:\n\n* `/swagger.json`: return OpenAPI specification file in json format\n* `/swagger-ui`: Swagger UI configured to hit OpenAPI json file\n* `/openapi.yaml`: return OpenAPI specification file in yaml format\n* `/redoc-ui`: ReDoc UI configured to hit OpenAPI yaml file\n\nThis come with a very simple extension that allow you to override basic settings of APISpec using your `config.py` file:\n\n* `APISPEC_TITLE`: title for your spec, default to `{{cookiecutter.project_name}}`\n* `APISPEC_VERSION`: version of your API, default to `1.0.0`\n* `OPENAPI_VERSION`: OpenAPI version of your spec, default to `3.0.2`\n* `SWAGGER_JSON_URL`: Url for your JSON specifications, default to `/swagger.json`\n* `SWAGGER_UI_URL`: Url for swagger-ui, default to `/swagger-ui`\n* `OPENAPI_YAML_URL`: Url for your YAML specifications, default to `/openapi.yaml`\n* `REDOC_UI_URL`: Url for redoc-ui, default to `/redoc-ui`\n* `SWAGGER_URL_PREFIX`: URL prefix to use for swagger blueprint, default to `None`\n\n## Changelog\n\n### 29/10/2021\n\n* Updated readme makefile calls\n* Fixed Makefile\n* Removed entrypoint from setup to use flask default CLI\n* Re-format apispec to fit black specs\n\n### 9/24/2021\n\n* Fixed CLI to work with Flask 2.0's built-in CLI\n* Added ReDoc UI and YAML OpenAPI Spec routes\n* Updated Swagger UI version to fix previously-distorted version\n* Updated README to reflect new CLI and ReDoc information\n\n### 6/08/2020\n\n* Updated README for tests and celery\n* Added a `.testenv` file to avoid needing to set env variables when running pytest manually\n* Updated celery fixtures to use session fixtures (for worker and app)\n* Replaced `prefork` in `celery_worker_pool` by `solo` (#41)\n\n### 18/01/2020\n\n* Added python 3.8 support\n* Upgraded to marshmallow 3\n* Added `lint` and `tests` envs to tox\n* Added black support\n* Improved travis tests\n* Updated Makefile to handle tests with celery\n* Updated tox to handle env variables for celery when runing tests\n* Added initial db migration instead of relying on `db.create_all()`\n* Added new step to create database in README\n* Various cleanup\n\n### 08/2019\n\n* Added apispec dependencies\n* Registered `users` endpoints into swagger\n* New `apispec` extension\n* Added two new routes `/swagger.json` and `/swagger-ui` (configurable urls)\n* Added swagger html template\n* Add travis file\n\n### 26/04/2019\n\n* Added docker and docker-compose support\n\n### 24/04/2019\n\n* Update configuration to only use env variables, `.flaskenv` has been updated too\n* Add unit tests for celery\n* Add flake8 to tox\n* Configuration file cannot be overridden by `MYAPP CONFIG` env variable anymore\n* various cleanups (unused imports, removed `configtest.py` file, flake8 errors)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarec%2Fcookiecutter-flask-restful","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkarec%2Fcookiecutter-flask-restful","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarec%2Fcookiecutter-flask-restful/lists"}