🌐 Add French translation for `docs/fr/docs/advanced/path-operation-advanced-configura...

Co-authored-by: Julian Maurin <julian.maurin.perso@pm.me>
Co-authored-by: Cedric Fraboulet <62244267+frabc@users.noreply.github.com>

diff --git a/docs/fr/docs/advanced/path-operation-advanced-configuration.md b/docs/fr/docs/advanced/path-operation-advanced-configuration.md
new file mode 100644 (file)
index 0000000..ace9f19
--- /dev/null
+++ b/docs/fr/docs/advanced/path-operation-advanced-configuration.md
@@ -0,0 +1,168 @@
+# Configuration avancée des paramètres de chemin
+
+## ID d'opération OpenAPI
+
+!!! Attention
+    Si vous n'êtes pas un "expert" en OpenAPI, vous n'en avez probablement pas besoin.
+
+Dans OpenAPI, les chemins sont des ressources, tels que /users/ ou /items/, exposées par votre API, et les opérations sont les méthodes HTTP utilisées pour manipuler ces chemins, telles que GET, POST ou DELETE. Les operationId sont des chaînes uniques facultatives utilisées pour identifier une opération d'un chemin. Vous pouvez définir l'OpenAPI `operationId` à utiliser dans votre *opération de chemin* avec le paramètre `operation_id`.
+
+Vous devez vous assurer qu'il est unique pour chaque opération.
+
+```Python hl_lines="6"
+{!../../../docs_src/path_operation_advanced_configuration/tutorial001.py!}
+```
+
+### Utilisation du nom *path operation function* comme operationId
+
+Si vous souhaitez utiliser les noms de fonction de vos API comme `operationId`, vous pouvez les parcourir tous et remplacer chaque `operation_id` de l'*opération de chemin* en utilisant leur `APIRoute.name`.
+
+Vous devriez le faire après avoir ajouté toutes vos *paramètres de chemin*.
+
+```Python hl_lines="2  12-21  24"
+{!../../../docs_src/path_operation_advanced_configuration/tutorial002.py!}
+```
+
+!!! Astuce
+    Si vous appelez manuellement `app.openapi()`, vous devez mettre à jour les `operationId` avant.
+
+!!! Attention
+    Pour faire cela, vous devez vous assurer que chacun de vos *chemin* ait un nom unique.
+
+    Même s'ils se trouvent dans des modules différents (fichiers Python).
+
+## Exclusion d'OpenAPI
+
+Pour exclure un *chemin* du schéma OpenAPI généré (et donc des systèmes de documentation automatiques), utilisez le paramètre `include_in_schema` et assignez-lui la valeur `False` :
+
+```Python hl_lines="6"
+{!../../../docs_src/path_operation_advanced_configuration/tutorial003.py!}
+```
+
+## Description avancée de docstring
+
+Vous pouvez limiter le texte utilisé de la docstring d'une *fonction de chemin* qui sera affiché sur OpenAPI.
+
+L'ajout d'un `\f` (un caractère d'échappement "form feed") va permettre à **FastAPI** de tronquer la sortie utilisée pour OpenAPI à ce stade.
+
+Il n'apparaîtra pas dans la documentation, mais d'autres outils (tel que Sphinx) pourront utiliser le reste.
+
+```Python hl_lines="19-29"
+{!../../../docs_src/path_operation_advanced_configuration/tutorial004.py!}
+```
+
+## Réponses supplémentaires
+
+Vous avez probablement vu comment déclarer le `response_model` et le `status_code` pour une *opération de chemin*.
+
+Cela définit les métadonnées sur la réponse principale d'une *opération de chemin*.
+
+Vous pouvez également déclarer des réponses supplémentaires avec leurs modèles, codes de statut, etc.
+
+Il y a un chapitre entier ici dans la documentation à ce sujet, vous pouvez le lire sur [Réponses supplémentaires dans OpenAPI](./additional-responses.md){.internal-link target=_blank}.
+
+## OpenAPI supplémentaire
+
+Lorsque vous déclarez un *chemin* dans votre application, **FastAPI** génère automatiquement les métadonnées concernant ce *chemin* à inclure dans le schéma OpenAPI.
+
+!!! note "Détails techniques"
+    La spécification OpenAPI appelle ces métaonnées des <a href="https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#operation-object" class="external-link" target="_blank">Objets d'opération</a>.
+
+Il contient toutes les informations sur le *chemin* et est utilisé pour générer automatiquement la documentation.
+
+Il inclut les `tags`, `parameters`, `requestBody`, `responses`, etc.
+
+Ce schéma OpenAPI spécifique aux *operations* est normalement généré automatiquement par **FastAPI**, mais vous pouvez également l'étendre.
+
+!!! Astuce
+    Si vous avez seulement besoin de déclarer des réponses supplémentaires, un moyen plus pratique de le faire est d'utiliser les [réponses supplémentaires dans OpenAPI](./additional-responses.md){.internal-link target=_blank}.
+
+Vous pouvez étendre le schéma OpenAPI pour une *opération de chemin* en utilisant le paramètre `openapi_extra`.
+
+### Extensions OpenAPI
+
+Cet `openapi_extra` peut être utile, par exemple, pour déclarer [OpenAPI Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specificationExtensions) :
+
+```Python hl_lines="6"
+{!../../../docs_src/path_operation_advanced_configuration/tutorial005.py!}
+```
+
+Si vous ouvrez la documentation automatique de l'API, votre extension apparaîtra au bas du *chemin* spécifique.
+
+<img src="/img/tutorial/path-operation-advanced-configuration/image01.png">
+
+Et dans le fichier openapi généré (`/openapi.json`), vous verrez également votre extension dans le cadre du *chemin* spécifique :
+
+```JSON hl_lines="22"
+{
+    "openapi": "3.0.2",
+    "info": {
+        "title": "FastAPI",
+        "version": "0.1.0"
+    },
+    "paths": {
+        "/items/": {
+            "get": {
+                "summary": "Read Items",
+                "operationId": "read_items_items__get",
+                "responses": {
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {
+                            "application/json": {
+                                "schema": {}
+                            }
+                        }
+                    }
+                },
+                "x-aperture-labs-portal": "blue"
+            }
+        }
+    }
+}
+```
+
+### Personnalisation du Schéma OpenAPI pour un chemin
+
+Le dictionnaire contenu dans la variable `openapi_extra` sera fusionné avec le schéma OpenAPI généré automatiquement pour l'*opération de chemin*.
+
+Ainsi, vous pouvez ajouter des données supplémentaires au schéma généré automatiquement.
+
+Par exemple, vous pouvez décider de lire et de valider la requête avec votre propre code, sans utiliser les fonctionnalités automatiques de validation proposée par Pydantic, mais vous pouvez toujours définir la requête dans le schéma OpenAPI.
+
+Vous pouvez le faire avec `openapi_extra` :
+
+```Python hl_lines="20-37 39-40"
+{!../../../docs_src/path_operation_advanced_configuration/tutorial006.py !}
+```
+
+Dans cet exemple, nous n'avons déclaré aucun modèle Pydantic. En fait, le corps de la requête n'est même pas <abbr title="converti d'un format simple, comme des octets, en objets Python">parsé</abbr> en tant que JSON, il est lu directement en tant que `bytes`, et la fonction `magic_data_reader()` serait chargé de l'analyser d'une manière ou d'une autre.
+
+Néanmoins, nous pouvons déclarer le schéma attendu pour le corps de la requête.
+
+### Type de contenu OpenAPI personnalisé
+
+En utilisant cette même astuce, vous pouvez utiliser un modèle Pydantic pour définir le schéma JSON qui est ensuite inclus dans la section de schéma OpenAPI personnalisée pour le *chemin* concerné.
+
+Et vous pouvez le faire même si le type de données dans la requête n'est pas au format JSON.
+
+Dans cet exemple, nous n'utilisons pas les fonctionnalités de FastAPI pour extraire le schéma JSON des modèles Pydantic ni la validation automatique pour JSON. En fait, nous déclarons le type de contenu de la requête en tant que YAML, et non JSON :
+
+```Python hl_lines="17-22  24"
+{!../../../docs_src/path_operation_advanced_configuration/tutorial007.py!}
+```
+
+Néanmoins, bien que nous n'utilisions pas la fonctionnalité par défaut, nous utilisons toujours un modèle Pydantic pour générer manuellement le schéma JSON pour les données que nous souhaitons recevoir en YAML.
+
+Ensuite, nous utilisons directement la requête et extrayons son contenu en tant qu'octets. Cela signifie que FastAPI n'essaiera même pas d'analyser le payload de la requête en tant que JSON.
+
+Et nous analysons directement ce contenu YAML, puis nous utilisons à nouveau le même modèle Pydantic pour valider le contenu YAML :
+
+```Python hl_lines="26-33"
+{!../../../docs_src/path_operation_advanced_configuration/tutorial007.py!}
+```
+
+!!! Astuce
+    Ici, nous réutilisons le même modèle Pydantic.
+
+    Mais nous aurions pu tout aussi bien pu le valider d'une autre manière.

diff --git a/docs/fr/mkdocs.yml b/docs/fr/mkdocs.yml
index 28fc795f94f7820d4a5487624197839e38c819bf..f5288a8fa819cb48b43d1a63aeb4e8d39c9178a0 100644 (file)
--- a/docs/fr/mkdocs.yml
+++ b/docs/fr/mkdocs.yml
@@ -70,6 +70,7 @@ nav:
   - tutorial/background-tasks.md
   - tutorial/debugging.md
 - Guide utilisateur avancé:
+  - advanced/path-operation-advanced-configuration.md
   - advanced/additional-status-codes.md
   - advanced/additional-responses.md
 - async.md