diff --git a/docs/fr/docs/tutorial/first-steps.md b/docs/fr/docs/tutorial/first-steps.md new file mode 100644 index 000000000..3a81362f6 --- /dev/null +++ b/docs/fr/docs/tutorial/first-steps.md @@ -0,0 +1,334 @@ +# Démarrage + +Le fichier **FastAPI** le plus simple possible pourrait ressembler à cela : + +```Python +{!../../../docs_src/first_steps/tutorial001.py!} +``` + +Copiez ce code dans un fichier nommé `main.py`. + +Démarrez le serveur : + +
+ +```console +$ uvicorn main:app --reload + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +INFO: Started reloader process [28720] +INFO: Started server process [28722] +INFO: Waiting for application startup. +INFO: Application startup complete. +``` + +
+ +!!! note + La commande `uvicorn main:app` fait référence à : + + * `main` : le fichier `main.py` (le module Python). + * `app` : l'objet créé dans `main.py` via la ligne `app = FastAPI()`. + * `--reload` : l'option disant à uvicorn de redémarrer le serveur à chaque changement du code. À ne pas utiliser en production ! + +Vous devriez voir dans la console, une ligne semblable à la suivante : + +```hl_lines="4" +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +Cette ligne montre l'URL par laquelle l'app est actuellement accessible, sur votre machine locale. + +### Allez voir le résultat + +Ouvrez votre navigateur à l'adresse http://127.0.0.1:8000. + +Vous obtiendrez cette réponse JSON : + +```JSON +{"message": "Hello World"} +``` + +### Documentation interactive de l'API + +Rendez-vous sur http://127.0.0.1:8000/docs. + +Vous verrez la documentation interactive de l'API générée automatiquement (via Swagger UI) : + +![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png) + +### Documentation alternative + +Ensuite, rendez-vous sur http://127.0.0.1:8000/redoc. + +Vous y verrez la documentation alternative (via ReDoc) : + +![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) + +### OpenAPI + +**FastAPI** génère un "schéma" contenant toute votre API dans le standard de définition d'API **OpenAPI**. + +#### "Schéma" + +Un "schéma" est une définition ou une description de quelque chose. Pas le code qui l'implémente, uniquement une description abstraite. + +#### "Schéma" d'API + +Ici, OpenAPI est une spécification qui dicte comment définir le schéma de votre API. + +Le schéma inclut les chemins de votre API, les paramètres potentiels de chaque chemin, etc. + +#### "Schéma" de données + +Le terme "schéma" peut aussi faire référence à la forme de la donnée, comme un contenu JSON. + +Dans ce cas, cela signifierait les attributs JSON, ainsi que les types de ces attributs, etc. + +#### OpenAPI et JSON Schema + +**OpenAPI** définit un schéma d'API pour votre API. Il inclut des définitions (ou "schémas") de la donnée envoyée et reçue par votre API en utilisant **JSON Schema**, le standard des schémas de données JSON. + +#### Allez voir `openapi.json` + +Si vous êtes curieux d'à quoi ressemble le schéma brut **OpenAPI**, **FastAPI** génère automatiquement un (schéma) JSON avec les descriptions de toute votre API. + +Vous pouvez le voir directement à cette adresse : http://127.0.0.1:8000/openapi.json. + +Le schéma devrait ressembler à ceci : + + +```JSON +{ + "openapi": "3.0.2", + "info": { + "title": "FastAPI", + "version": "0.1.0" + }, + "paths": { + "/items/": { + "get": { + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + + + +... +``` + +#### À quoi sert OpenAPI + +Le schéma **OpenAPI** est ce qui alimente les deux systèmes de documentation interactive. + +Et il existe des dizaines d'alternatives, toutes basées sur **OpenAPI**. Vous pourriez facilement ajouter n'importe laquelle de ces alternatives à votre application **FastAPI**. + +Vous pourriez aussi l'utiliser pour générer du code automatiquement, pour les clients qui communiquent avec votre API. Comme par exemple, des applications frontend, mobiles ou IOT. + +## Récapitulatif, étape par étape + +### Étape 1 : import `FastAPI` + +```Python hl_lines="1" +{!../../../docs_src/first_steps/tutorial001.py!} +``` + +`FastAPI` est une classe Python qui fournit toutes les fonctionnalités nécessaires au lancement de votre API. + +!!! note "Détails techniques" + `FastAPI` est une classe héritant directement de `Starlette`. + + Vous pouvez donc aussi utiliser toutes les fonctionnalités de Starlette depuis `FastAPI`. + +### Étape 2 : créer une "instance" `FastAPI` + +```Python hl_lines="3" +{!../../../docs_src/first_steps/tutorial001.py!} +``` + +Ici la variable `app` sera une "instance" de la classe `FastAPI`. + +Ce sera le point principal d'interaction pour créer toute votre API. + +Cette `app` est la même que celle à laquelle fait référence `uvicorn` dans la commande : + +
+ +```console +$ uvicorn main:app --reload + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +Si vous créez votre app avec : + +```Python hl_lines="3" +{!../../../docs_src/first_steps/tutorial002.py!} +``` + +Et la mettez dans un fichier `main.py`, alors vous appeleriez `uvicorn` avec : + +
+ +```console +$ uvicorn main:my_awesome_api --reload + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +### Étape 3: créer une *opération de chemin* + +#### Chemin + +Chemin, ou "path" fait référence ici à la dernière partie de l'URL démarrant au premier `/`. + +Donc, dans un URL tel que : + +``` +https://example.com/items/foo +``` + +...le "path" serait : + +``` +/items/foo +``` + +!!! info + Un chemin, ou "path" est aussi souvent appelé route ou "endpoint". + + +#### Opération + +"Opération" fait référence à une des "méthodes" HTTP. + +Une de : + +* `POST` +* `GET` +* `PUT` +* `DELETE` + +...ou une des plus exotiques : + +* `OPTIONS` +* `HEAD` +* `PATCH` +* `TRACE` + +Dans le protocol HTTP, vous pouvez communiquer avec chaque chemin en utilisant une (ou plus) de ces "méthodes". + +--- + +En construisant des APIs, vous utilisez généralement ces méthodes HTTP spécifiques pour effectuer une action précise. + +Généralement vous utilisez : + +* `POST` : pour créer de la donnée. +* `GET` : pour lire de la donnée. +* `PUT` : pour mettre à jour de la donnée. +* `DELETE` : pour supprimer de la donnée. + +Donc, dans **OpenAPI**, chaque méthode HTTP est appelée une "opération". + +Nous allons donc aussi appeler ces dernières des "**opérations**". + + +#### Définir un *décorateur d'opération de chemin* + +```Python hl_lines="6" +{!../../../docs_src/first_steps/tutorial001.py!} +``` + +Le `@app.get("/")` dit à **FastAPI** que la fonction en dessous est chargée de gérer les requêtes qui vont sur : + +* le chemin `/` +* en utilisant une opération get + +!!! info "`@décorateur` Info" + Cette syntaxe `@something` en Python est appelée un "décorateur". + + Vous la mettez au dessus d'une fonction. Comme un joli chapeau décoratif (j'imagine que ce terme vient de là 🤷🏻‍♂). + + Un "décorateur" prend la fonction en dessous et en fait quelque chose. + + Dans notre cas, ce décorateur dit à **FastAPI** que la fonction en dessous correspond au **chemin** `/` avec l'**opération** `get`. + + C'est le "**décorateur d'opération de chemin**". + +Vous pouvez aussi utiliser les autres opérations : + +* `@app.post()` +* `@app.put()` +* `@app.delete()` + +Tout comme celles les plus exotiques : + +* `@app.options()` +* `@app.head()` +* `@app.patch()` +* `@app.trace()` + +!!! tip "Astuce" + Vous êtes libres d'utiliser chaque opération (méthode HTTP) comme vous le désirez. + + **FastAPI** n'impose pas de sens spécifique à chacune d'elle. + + Les informations qui sont présentées ici forment une directive générale, pas des obligations. + + Par exemple, quand l'on utilise **GraphQL**, toutes les actions sont effectuées en utilisant uniquement des opérations `POST`. + +### Étape 4 : définir la **fonction de chemin**. + +Voici notre "**fonction de chemin**" (ou fonction d'opération de chemin) : + +* **chemin** : `/`. +* **opération** : `get`. +* **fonction** : la fonction sous le "décorateur" (sous `@app.get("/")`). + +```Python hl_lines="7" +{!../../../docs_src/first_steps/tutorial001.py!} +``` + +C'est une fonction Python. + +Elle sera appelée par **FastAPI** quand une requête sur l'URL `/` sera reçue via une opération `GET`. + +Ici, c'est une fonction asynchrone (définie avec `async def`). + +--- + +Vous pourriez aussi la définir comme une fonction classique plutôt qu'avec `async def` : + +```Python hl_lines="7" +{!../../../docs_src/first_steps/tutorial003.py!} +``` + +!!! note + Si vous ne connaissez pas la différence, allez voir la section [Concurrence : *"Vous êtes pressés ?"*](../async.md#vous-etes-presses){.internal-link target=_blank}. + +### Étape 5 : retourner le contenu + +```Python hl_lines="8" +{!../../../docs_src/first_steps/tutorial001.py!} +``` + +Vous pouvez retourner un dictionnaire (`dict`), une liste (`list`), des valeurs seules comme des chaines de caractères (`str`) et des entiers (`int`), etc. + +Vous pouvez aussi retourner des models **Pydantic** (qui seront détaillés plus tard). + +Il y a de nombreux autres objets et modèles qui seront automatiquement convertis en JSON. Essayez d'utiliser vos favoris, il est fort probable qu'ils soient déjà supportés. + +## Récapitulatif + +* Importez `FastAPI`. +* Créez une instance d'`app`. +* Ajoutez une **décorateur d'opération de chemin** (tel que `@app.get("/")`). +* Ajoutez une **fonction de chemin** (telle que `def root(): ...` comme ci-dessus). +* Lancez le serveur de développement (avec `uvicorn main:app --reload`). diff --git a/docs/fr/mkdocs.yml b/docs/fr/mkdocs.yml index 01cf8d5e0..6242a88fd 100644 --- a/docs/fr/mkdocs.yml +++ b/docs/fr/mkdocs.yml @@ -59,6 +59,7 @@ nav: - fastapi-people.md - python-types.md - Tutoriel - Guide utilisateur: + - tutorial/first-steps.md - tutorial/path-params.md - tutorial/query-params.md - tutorial/body.md