Alternatives et Comparaison¶

Flask-Jeroboam existe dans un espace avec plusieurs autres bibliothèques. Cette page vous donne une comparaison honnête pour que vous puissiez choisir le bon outil pour votre situation.

Le paysage¶

Bibliothèque	Téléchargements mensuels	Approche	Pydantic	Validation des réponses
flask-restx	~2,6M	Ressources basées sur les classes, Swagger UI	❌ Aucun	❌
flask-smorest	~1,3M	Basée sur Marshmallow, OpenAPI	❌ Marshmallow	❌
flask-openapi3	~2,2M	Injection de modèles nommés	✅ v2	Optionnelle
apiflask	~227K	Remplacement au niveau du cadre	Partielle	❌
spectree	~252K	Validation basée sur les décorateurs	✅ v1+v2	Optionnelle
flask-jeroboam	—	Style FastAPI par paramètre	✅ v2	✅ Par défaut

Flask-Jeroboam vs flask-openapi3¶

Flask-openapi3 est l’alternative fonctionnelle la plus proche et vaut la peine d’être comprise en profondeur avant de choisir entre elles.

La différence de conception centrale¶

Les deux bibliothèques ont fait des paris opposés au cœur de leur API de déclaration de paramètres.

flask-openapi3 utilise des noms d’arguments magiques réservés. Vous groupez tous les paramètres d’un emplacement HTTP donné dans un seul modèle Pydantic, puis passez ce modèle comme argument de fonction dont le nom indique à la bibliothèque où chercher :

# flask-openapi3
class BookQuery(BaseModel):
    page: int = 1
    per_page: int = 10

class BookBody(BaseModel):
    title: str
    author: str

@app.post("/books")
def create_book(query: BookQuery, body: BookBody):
    # "query" et "body" sont des chaînes magiques — les noms déterminent la détection de localisation
    pass

Flask-Jeroboam utilise des paramètres de fonction individuels, avec la localisation déduite du contexte (verbe HTTP, motif de route) ou déclarée explicitement par paramètre — le même motif que FastAPI :

# flask-jeroboam
@app.post("/books")
def create_book(page: int = 1, per_page: int = 10, title: str, author: str):
    # page, per_page → requête (déduit : paramètres de style GET)
    # title, author  → corps (déduit : défaut du verbe POST)
    # Pas de noms magiques, pas de modèles wrapper requis
    pass

Ce n’est pas juste du sucre syntaxique. Le choix architectural a des conséquences réelles.

Où Flask-Jeroboam a un avantage structurel¶

1. Composition des décorateurs et des middleware¶

Flask-openapi3 valide les requêtes en interceptant **kwargs au moment de l’appel et en traitant tout comme un argument de chemin. Cela casse tout décorateur qui injecte des arguments de mots-clés — décorateurs d’authentification, frameworks d’injection de dépendances, limiteurs de débit. Le résultat : les requêtes non authentifiées retournent 422 Validation Error au lieu de 401 Unauthorized car la validation s’exécute avant l’authentification (problème flask-openapi3 #111, #143).

Flask-Jeroboam résout toutes les métadonnées des paramètres au moment de l’enregistrement (quand le décorateur s’exécute), pas au moment de la requête. La signature de la fonction de vue est inspectée une fois et un gestionnaire dédié est construit. Les décorateurs Flask standard se composent naturellement.

2. Validation des réponses comme une fonctionnalité de première classe¶

Flask-openapi3 a été construit pour la génération de documentation ; la validation des réponses a été ajoutée plus tard en tant qu’option opt-in (validate_response=True). L’implémentation place un drapeau sur l’objet fonction, et le PR qui l’a ajouté a été immédiatement suivi d’un bug AttributeError (#246).

Flask-Jeroboam a une validation bidirectionnelle dès le départ. Le OutboundHandler est un pair du InboundHandler, pas une pensée tardive. La validation des réponses est activée par défaut — si votre vue retourne des données qui ne correspondent pas au response_model déclaré, vous obtenez une ResponseValidationError en développement avant qu’elle n’atteigne un client.

3. Pas de réimplémentation du schéma Pydantic¶

Flask-openapi3 réimplémente la traversée du schéma Pydantic en interne. C’est la cause profonde d’une classe récurrente de bogues : les propriétés @computed_field disparaissent de la documentation OpenAPI (#139), les tuples se cassent après les mises à jour de version (#183), les alias de champs cessent de fonctionner pour les données de formulaire (#182), et les avertissements de dépréciation de Field(example=...) (#176, #177).

Flask-Jeroboam délègue la génération de schéma à la propre fonction model_json_schema() de Pydantic plutôt que de la réimplémenter. Cette classe de bogue ne peut pas survenir par conception.

4. Paramètres scalaires individuels sans modèles wrapper¶

Dans flask-openapi3, même un seul paramètre de requête nécessite d’être enrobé dans un BaseModel :

# flask-openapi3 — vous avez besoin d'un modèle pour un seul paramètre
class PaginationQuery(BaseModel):
    page: int = 1

@app.get("/items")
def list_items(query: PaginationQuery):
    pass

Dans Flask-Jeroboam, les scalaires individuels fonctionnent directement :

# flask-jeroboam — pas de wrapper nécessaire
@app.get("/items")
def list_items(page: int = 1):
    pass

5. Valeurs par défaut intelligentes basées sur les verbes HTTP¶

Flask-Jeroboam déduit la localisation des paramètres du verbe HTTP — GET/HEAD/DELETE par défaut à la chaîne de requête ; POST/PUT/PATCH par défaut au corps de la requête. Cela supprime le besoin d’annoter la plupart des paramètres explicitement, tout en permettant les remplacements avec Query(), Body(), Header(), etc.

Où flask-openapi3 a un avantage structurel¶

Support de Pydantic v2. Les deux bibliothèques supportent Pydantic v2 nativement. Flask-Jeroboam v0.2.0 a terminé une migration complète vers Pydantic v2 sans couche de compatibilité v1.

Plus d’options d’interface utilisateur de documentation. Flask-openapi3 supporte Swagger UI, ReDoc, RapiDoc, Scalar et Elements. Flask-Jeroboam fournit actuellement Swagger UI.

Une plus grande base installée. Plus d’utilisateurs signifie plus de tests en conditions réelles, plus de réponses Stack Overflow et plus de probabilité que votre question spécifique ait déjà été posée.

Résumé¶

Choisissez flask-openapi3 si :

Vous préférez le groupement explicite des modèles à la place des déclarations par paramètre
Vous avez besoin d’options d’interface utilisateur ReDoc, Scalar ou autres au-delà de Swagger

Choisissez Flask-Jeroboam si :

Vous êtes familiarisé avec FastAPI et voulez cette syntaxe exacte de paramètres
Vous avez besoin de la validation des réponses activée par défaut, pas optionnelle
Vous avez besoin d’une composition claire des décorateurs/middleware sans surprises d’ordre de validation
Vous voulez que la génération du schéma Pydantic soit déléguée à Pydantic lui-même, pas réimplémentée

Flask-Jeroboam vs FastAPI¶

FastAPI n’est pas une extension Flask — c’est un framework séparé construit sur Starlette/ASGI. Flask-Jeroboam est explicitement modélisé d’après la syntaxe des paramètres de FastAPI, donc la plupart des motifs FastAPI se transfèrent directement.

Choisissez FastAPI si :

Vous démarrez un nouveau projet sans héritage Flask
Vous avez besoin d’async/await natif partout
Les performances d’ASGI sont une exigence