💻 A full-featured Flask + API + OAS3 + JWT + SwaggerUI + ORM + Migrations + Great and Scalable structure project template
👉 It's using latest Flask 1.2
Flask 2 is coming soon 😎
It uses PostgreSQL everywhere, so Docker is necessary (SQLite with no Docker dependency is on the roadmap) 😎
- Focus on the business and creating value
- Faster project setup
- Standard project structure organization (easy to scale)
- Better QA
- API Design first using OpenAPI & Connexion
- API documentation using swagger UI
- Login using JWT
- Every layer is separated in context/domain
- Service layer for better tests and reuse
- Using Flask Factory to integrate with extensions
- Migrations using Alembic
- ORM using SQLAlchemy
- Optimized development and production settings
- Comes with user model ready to go, # & signin
- Procfile for deploying to Heroku
- Customizable PostgreSQL version
- Tests using pytest
- Unit tests for the API layer
- Unit tests for the service layer
Development
- Code linter
- Code formatter (Black+iSort)
- Using .env file
- Docker support using docker-compose for development
- Docker using multistage (Production Ready Dockerfile)
- Postgres in development (using docker-compose)
- CI using Github Actions
This project is organized in:
- Layers 🧅, which might not change in the project life cycle
- Modules 📦, for domain contexts, which might scale in terms of new features
- Configuration ⚙️ separated based on the extensions
- The 🎂 Business modules
Hackernews-Clone
.
├── hackernews
│ ├── app.py 👉 Entrypoint (create_app)
│ ├── exceptions.py
│ ├── 🧅 ext 👉 Settings
│ │ ├── ⚙️ configuration.py
│ │ ├── ⚙️ api.py
│ │ └── ⚙️ database.py
│ │ ...
│ ├── 🧅 api 👉 API Routes
│ │ ├── 📦 auth.py
│ │ ├── 📦 news.py
│ │ └── 📦 openapi.yaml 👉 API Contract
│ │ ...
│ ├── 🧅 services 👉 Business rules
│ │ ├── 📦 auth.py 🎂
│ │ ├── 📦 news.py 🎂
│ │ └── 📦 token.py 🎂
│ │ ...
│ └── 🧅 models 👉 ORM
│ ├── 📦 news.py
│ └── 📦 users.py
│ ...
├── ⚙️ migrations 👉 Database versions
│ ├── alembic.ini
│ ├── env.py
│ ├── script.py.mako
│ └── versions
├── tests
│ ├── conftest.py
│ ├── api 👉 Endpoint tests, input, output and validation
│ ├── database 👉 Database connection tests
│ └── services 👉 Business rules tests
├── requirements.txt
├── pytest.ini
├── uwsgi.ini 👉 Application server settings
└── wsgi.py 👉 WSGI Deploy file (Gunicorn/uWSGI)
-
Python 3.8 or 3.9 (Help us test in other versions)
-
Docker to run Postgres locally
Any help is more than welcome...
- 👉 It could be an Issue
- 💻 It could be using it and give a feedback
- 🌟 It could be a github star
- 🤔 It could be a Question
- 🤔 If you dislike this project, feel free to tell us what is wrong with it
Let's pretend you want to create a Flask project called "hackernewsclone". Rather than start from scratch by a app.py and add each library, Flask extesion and various other configurations that always get forgotten until the worst possible moment, get this cookiecutter template do all the work.
First, get Cookiecutter. Trust me, it's awesome::
$ pip install "cookiecutter>=1.7.0"
Now run it against this repo::
$ cookiecutter https://github.com/huogerac/cookiecutter-flask-openapi/
You'll be prompted for some values. Provide them...
project_name [Hackernews Clone]:
project_slug [hackernews_clone]: hackernews
description [The Ultimate Flask Template]:
main_model [News]: News
main_model_lower [news]:
Select python_version:
1 - 3.8.10
2 - 3.9.5
Choose from 1, 2 [1]: 2
Select package_manager:
1 - requirements.txt
2 - Pipenv
Choose from 1, 2 [1]:
Select postgresql_version:
1 - 13.3-alpine
2 - 13.5
3 - 14.1
Choose from 1, 2, 3 [1]:
use_dockerfile [yes]:
use_github_actions_CI [yes]:
deploy_to_heroku [yes]:
keep_vscode_settings [yes]:
author_name [Roger Camargo]:
email [roger-camargo@example.com]: huogerac@gmail.com
version [0.1.0]:
[INFO]: - Using requirements.txt and virtualenv
[SUCCESS]: 🐍 Your project is created! ✨ 🍰 ✨
What's next?
cd hackernews
Check the README_DOCKER 🐳
Check the README_VIRTUALENV 🐍
[INFO]: ⚠️ For more details, check the Makefile or run: make help
Then access 🚀 http://localhost:5000/api
The big difference in this template is the way APIs are created, it uses the connexion to build up the API Contract (YAML) first. So the API documentation is created from the contract and not from code.
We can start new implementation from building tests (TDD)
# API tests
def test_should_return_title_is_a_required_field(token_valid_mock, client):
# Given a request with a missing required field
response = client.post(
"/api/news",
headers={"authorization": f"Bearer {token_valid_mock}"},
json={},
)
# Then
assert response.status_code == 400
assert response.json["detail"] == "'title' is a required property"
def test_should_reject_title_less_than_min_title_length(token_valid_mock, client):
# Given a request with an invalid title
response = client.post(
"/api/news",
headers={"authorization": f"Bearer {token_valid_mock}"},
json={"title": "tiny-title"},
)
# Then
assert response.status_code == 400
assert response.json["detail"] == "'tiny-title' is too short - 'title'"
@patch("hackernews.services.news.create_news")
def test_should_accept_null_description(news_mock, token_valid_mock, client):
news_mock.return_value = {}
# Given a request with an empty description (non string)
response = client.post(
"/api/news",
headers={"authorization": f"Bearer {token_valid_mock}"},
json={
"title": "A valid and simple title",
"description": None,
},
)
# Then
assert response.status_code == 201
news_mock.assert_called_once_with("A valid and simple title", None)Then, we jump up directly to the API Contract. Note that the contract has information to do input validations
# hackernews/api/openapi.yaml
/api/news:
post:
operationId: hackernews.api.news.create_news
summary: Creates a news
tags:
- News
security:
- jwtAuth: [news:create]
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- title
properties:
title:
type: string
example: This is an awesome news
minLength: 12
description:
type: string
example: Some extra information about the news
nullable: true
responses:
201:
description: News created succesfully
content:
application/json:
schema:
$ref: "#/components/schemas/News"
400:
description: Invalid data
401:
description: No Authorization
components:
schemas:
News:
type: object
properties:
id:
type: integer
example: 42
title:
type: string
example: Python is a great option for backend and APIs
description:
type: string
example: This is along text within more detailed information about the news
nullable: true
created_at:
type: string
format: date-time
example: 2021-01-11T11:32:28Z-
This template is based on cookiecutter-django. Thanks PyDanny and the Cookiecutter maintainers
-
This Flask structure is based on "Arquitetura Definitiva para o Projeto Web Com Python e Flask". Thanks Bruno Rocha and all yours awesome Flask contents