Aller au contenu

Configurer OpenAPI de manière conditionnelle

🌐 Traduction par IA et humains

Cette traduction a été réalisée par une IA guidée par des humains. 🤝

Elle peut contenir des erreurs d'interprétation du sens original, ou paraître peu naturelle, etc. 🤖

Vous pouvez améliorer cette traduction en nous aidant à mieux guider le LLM d'IA.

Version anglaise

Si nécessaire, vous pouvez utiliser des paramètres et des variables d'environnement pour configurer OpenAPI de manière conditionnelle selon l'environnement, et même le désactiver complètement.

À propos de la sécurité, des API et de la documentation

Masquer vos interfaces utilisateur de la documentation en production ne devrait pas être la manière de protéger votre API.

Cela n'ajoute aucune sécurité supplémentaire à votre API, les chemins d'accès resteront disponibles là où ils se trouvent.

S'il y a une faille de sécurité dans votre code, elle existera toujours.

Masquer la documentation rend simplement plus difficile la compréhension de la manière d'interagir avec votre API et pourrait aussi rendre son débogage en production plus difficile. Cela pourrait être considéré simplement comme une forme de Sécurité par l'obscurité.

Si vous voulez sécuriser votre API, il y a plusieurs meilleures approches possibles, par exemple :

  • Vous devez vous assurer d'avoir des modèles Pydantic bien définis pour le corps de la requête et la réponse.
  • Configurez toutes les autorisations et tous les rôles nécessaires à l'aide de dépendances.
  • Ne stockez jamais de mots de passe en clair, seulement des hachages de mots de passe.
  • Implémentez et utilisez des outils cryptographiques reconnus, comme pwdlib et des jetons JWT, ... etc.
  • Ajoutez des contrôles d'autorisation plus granulaires avec des scopes OAuth2 lorsque nécessaire.
  • ... etc.

Néanmoins, vous pourriez avoir un cas d'utilisation très spécifique où vous devez vraiment désactiver la documentation de l'API pour un certain environnement (par exemple pour la production) ou selon des configurations provenant de variables d'environnement.

Configurer OpenAPI de manière conditionnelle avec des paramètres et des variables d'environnement

Vous pouvez facilement utiliser les mêmes paramètres Pydantic pour configurer votre OpenAPI généré et les interfaces utilisateur de la documentation.

Par exemple :

from fastapi import FastAPI
from pydantic_settings import BaseSettings


class Settings(BaseSettings):
    openapi_url: str = "/openapi.json"


settings = Settings()

app = FastAPI(openapi_url=settings.openapi_url)


@app.get("/")
def root():
    return {"message": "Hello World"}

Ici nous déclarons le paramètre openapi_url avec la même valeur par défaut "/openapi.json".

Nous l'utilisons ensuite lors de la création de l'application FastAPI.

Vous pouvez alors désactiver OpenAPI (y compris les interfaces utilisateur de la documentation) en définissant la variable d'environnement OPENAPI_URL sur la chaîne vide, comme ceci :

$ OPENAPI_URL= uvicorn main:app

<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Ensuite, si vous allez aux URL /openapi.json, /docs ou /redoc, vous obtiendrez simplement une erreur 404 Not Found comme :

{
    "detail": "Not Found"
}