fern-api · dsinghvi · Apr 7, 2026
@@ -0,0 +1,54 @@
+---
+title: Personnaliser la mise en page de la référence API
+description: Personnalisez la mise en page de votre référence API avec Fern. Configurez les options, ordonnez les sections et endpoints, aplatissez la navigation, masquez des endpoints, affichez les erreurs et ajoutez du contenu personnalisé.
+---
+
+
+Lorsque vous [incluez une API dans votre fichier `docs.yml`](/learn/docs/api-references/generate-api-ref), vous pouvez personnaliser la façon dont les endpoints et les sections sont affichés dans la navigation latérale. Par défaut, la référence génère une hiérarchie de navigation basée sur la structure de la spécification API, mais plusieurs personnalisations peuvent être configurées.
+
+<Note title="Sections API">
+Si vous utilisez une spécification OpenAPI, les sections sont créées à partir de la propriété `tags`, convertie en convention `lowerCamelCase` (ex. : createUser). Si vous utilisez une Fern Definition, les sections sont créées à partir des noms de fichiers [`service`](/learn/api-definitions/ferndef/endpoints/overview#service-definition).
+</Note>
+
+Si vous souhaitez n'afficher qu'un sous-ensemble d'endpoints, consultez la propriété Audiences pour les [spécifications OpenAPI](/learn/api-definitions/openapi/extensions/audiences) ou les [Fern Definitions](/learn/api-definitions/ferndef/audiences).
+
+## Ordonner la référence API
+
+### Tri alphabétique des endpoints et sections
+
+Pour trier tous les sections et endpoints par ordre alphabétique, sauf ceux explicitement ordonnés dans `layout`, définissez `alphabetized` sur `true`.
+
+```yaml title="docs.yml"
+navigation: 
+  - api: API Reference
+    alphabetized: true
+```
+
+### Ordonner les sections de premier niveau
+
+L'option `layout` vous permet de spécifier l'ordre des sous-packages, sections, endpoints et pages au premier niveau de votre référence API.
+
+<Tabs>
+  <Tab title="Spécification OpenAPI">
+  ```yaml title="docs.yml"
+  navigation: 
+    - api: API Reference
+      layout: 
+        - POST /user
+        - user
+        - store
+        - plant
+  ```
+  </Tab>
+  <Tab title="Fern Definition">
+  ```yaml title="docs.yml"
+  navigation: 
+    - api: API Reference
+      layout: 
+        - user.create
+        - user
+        - store
+        - plant
+  ```
+  </Tab>
+</Tabs>
@@ -0,0 +1,106 @@
+---
+title: Générer une référence API REST
+description: Utilisez Fern Docs pour générer une documentation de référence API REST à partir d'une spécification OpenAPI ou d'une Fern Definition.
+---
+
+
+Fern génère une documentation de référence API REST à partir d'une [spécification OpenAPI](/learn/api-definitions/openapi/overview) ou d'une [Fern Definition](/learn/api-definitions/ferndef/overview). Une fois la définition de l'API configurée, il suffit d'ajouter une seule ligne de configuration pour l'intégrer à la documentation.
+
+<Tip>
+  Fern prend également en charge les références [gRPC](/learn/docs/api-references/generate-grpc-ref), [WebSocket](/learn/docs/api-references/generate-websocket-ref) (AsyncAPI ou Fern Definition), [OpenRPC](/learn/docs/api-references/generate-openrpc-ref) et [Webhook](/learn/docs/api-references/generate-webhook-ref).
+</Tip>
+
+## Configuration
+
+<Steps>
+<Step title="Configurer la structure du projet">
+
+Pour **OpenAPI/AsyncAPI** : Ajoutez votre fichier de spécification à votre répertoire `/fern` et créez un `generators.yml` qui le référence dans la section `api.specs`
+
+Pour **Fern Definition** : Ajoutez un répertoire `definition/` avec vos fichiers de définition d'API (Fern le détecte automatiquement)
+
+```yaml generators.yml
+api:
+  specs:
+    - openapi: "./openapi.yml"
+```
+
+
+</Step>
+<Step title="Ajouter la référence API à la navigation">
+
+Ajoutez `- api: API Reference` à votre navigation dans `docs.yml` :
+
+```yml docs.yml
+navigation:
+  - api: API Reference
+```
+
+Fern remplira automatiquement vos endpoints, types et extraits de code à partir de votre définition d'API. Les exemples de requêtes et de réponses sont [générés par IA](/learn/docs/ai-features/ai-examples) pour afficher des données réalistes au lieu de valeurs fictives.
+</Step>
+<Step title="Personnaliser la mise en page">
+
+Pour une liste complète des options de configuration et des personnalisations de mise en page, consultez [Personnaliser la mise en page de la référence API](/learn/docs/api-references/customize-api-reference-layout).
+
+</Step>
+</Steps>
+
+### Inclure plusieurs références API
+
+Pour inclure plusieurs définitions d'API distinctes dans votre documentation, utilisez la propriété `api-name`. Le `api-name` correspond au nom du dossier contenant votre définition d'API.
+
+Cela fonctionne avec n'importe quelle combinaison de formats OpenAPI et Fern Definition. Par exemple :
+
+<Files>
+  <Folder name="fern" defaultOpen>
+    <File name="fern.config.json" />
+    <File name="docs.yml" />
+    <Folder name="plant-api" defaultOpen>
+      <File name="openapi.yml" comment="Spécification OpenAPI" />
+      <File name="generators.yml" comment="Référence la spécification OpenAPI" />
+    </Folder>
+    <Folder name="garden-api" defaultOpen>
+      <Folder name="definition" defaultOpen>
+        <File name="api.yml" />
+      </Folder>
+    </Folder>
+  </Folder>
+</Files>
+
+<Tabs>
+<Tab title="Mise en page simple">
+Pour une configuration simple sans onglets, vous pouvez inclure plusieurs références API directement dans votre navigation :
+
+```yaml title="docs.yml"
+navigation:
+  - api: Plant Store
+    api-name: plant-api   # Correspond au nom du dossier contenant votre définition d'API
+  - api: Garden
+    api-name: garden-api  # Correspond au nom du dossier contenant votre définition d'API
+```
+</Tab>
+<Tab title="Mise en page avec onglets">
+Lors de l'utilisation d'onglets, chaque référence API doit être placée dans le `layout` d'un onglet :
+
+```yaml title="docs.yml" {12, 17}
+tabs:
+  plant-api:
+    display-name: Plant Store API
+    icon: leaf
+  garden-api:
+    display-name: Garden API
+    icon: tree
+navigation:
+  - tab: plant-api
+    layout:
+      - api: Plant Store API
+        api-name: plant-api
+        skip-slug: true
+  - tab: garden-api
+    layout:
+      - api: Garden API
+        api-name: garden-api
+        skip-slug: true
+```
+</Tab>
+</Tabs>
@@ -0,0 +1,83 @@
+---
+title: Générer une référence GraphQL
+description: Utilisez Fern Docs pour générer une documentation de référence API GraphQL à partir d'un schéma GraphQL.
+availability: pre-release
+---
+
+<Warning>La référence API GraphQL n'est pas activement maintenue. [Contactez-nous](https://buildwithfern.com/contact) si vous avez des questions.</Warning>
+
+Fern génère une documentation de référence API à partir d'un [schéma GraphQL](https://graphql.org/learn/schema/). Ajoutez votre fichier de schéma à votre projet Fern et Fern affiche les requêtes, mutations, abonnements et types sous forme de référence interactive.
+
+## Configuration
+
+<Steps>
+<Step title="Configurer la structure du projet">
+
+Ajoutez votre fichier de schéma GraphQL à votre répertoire `/fern` et créez un `generators.yml` qui le référence :
+
+```yaml generators.yml
+api:
+  specs:
+    - graphql: plants.schema.graphql
+      name: Plants
+      origin: https://api.example.com/plants/graphql
+```
+
+</Step>
+<Step title="Ajouter la référence GraphQL à la navigation">
+
+Ajoutez `- api: API Reference` à votre navigation dans `docs.yml` :
+
+```yml docs.yml
+navigation:
+  - api: API Reference
+```
+
+</Step>
+<Step title="Personnaliser la mise en page">
+
+Pour une liste complète des options de configuration et des personnalisations de mise en page, consultez [Personnaliser la mise en page de la référence API](/learn/docs/api-references/customize-api-reference-layout).
+
+</Step>
+</Steps>
+
+### Inclure plusieurs références GraphQL
+
+Pour inclure plusieurs définitions GraphQL dans votre documentation, utilisez la propriété `api-name`. Le `api-name` correspond au nom du dossier contenant votre schéma GraphQL.
+
+<Files>
+  <Folder name="fern" defaultOpen>
+    <File name="fern.config.json" />
+    <File name="docs.yml" />
+    <Folder name="plant-graphql" defaultOpen>
+      <File name="schema.graphql" comment="Schéma GraphQL Plant" />
+      <File name="generators.yml" />
+    </Folder>
+    <Folder name="garden-graphql" defaultOpen>
+      <File name="schema.graphql" comment="Schéma GraphQL Garden" />
+      <File name="generators.yml" />
+    </Folder>
+  </Folder>
+</Files>
+
+```yaml title="docs.yml"
+navigation:
+  - api: Plant GraphQL API
+    api-name: plant-graphql
+  - api: Garden GraphQL API
+    api-name: garden-graphql
+```
+
+### Propriétés de configuration
+
+<ParamField path="api.specs[].graphql" required>
+  Chemin vers votre fichier de schéma GraphQL. Vous pouvez inclure plusieurs spécifications GraphQL si votre projet expose plus d'une API GraphQL.
+</ParamField>
+
+<ParamField path="api.specs[].name">
+  Nom du dossier sous lequel les opérations de cette spécification apparaissent dans la barre latérale de la référence API. Utilisez ceci pour regrouper les opérations GraphQL associées.
+</ParamField>
+
+<ParamField path="api.specs[].origin">
+  URL de votre endpoint API GraphQL. Fern effectue une [introspection](https://graphql.org/learn/introspection/) sur cet endpoint pour récupérer le schéma. Lorsque défini, l'exécution de [`fern api update`](/learn/cli-api-reference/cli-reference/commands#fern-api-update) met à jour le schéma local depuis cet endpoint.
+</ParamField>
@@ -0,0 +1,98 @@
+---
+title: Masquer du contenu sur votre site
+description: Contrôlez la visibilité des pages, sections, versions et endpoints API en les masquant de votre barre latérale et des résultats de recherche.
+---
+
+Fern vous offre deux outils principaux pour contrôler la visibilité du contenu : `hidden: true` dans `docs.yml` supprime le contenu de la barre latérale et des résultats de recherche de votre site, tandis que `noindex: true` dans le frontmatter d'une page exclut une page de la recherche sans affecter la navigation.
+
+## Masquer une page
+
+### Accessible uniquement par URL directe
+
+Définissez `hidden: true` dans `docs.yml` pour supprimer une page de la barre latérale, des résultats de recherche et de [llms.txt](/learn/docs/ai-features/llms-txt) tout en la gardant accessible via un lien direct. Ceci est utile pour partager des brouillons de documentation avec des réviseurs ou pour créer des liens depuis des outils externes comme les tickets de support. Il n'est pas nécessaire de définir également `noindex` — `hidden: true` gère les deux automatiquement.
+
+```yaml title="docs.yml" {4}
+navigation:
+  - section: Introduction
+    contents:
+      - page: My Page
+        path: ./pages/my-page.mdx
+      - page: Hide and Seek
+        hidden: true
+        path: ./pages/hide-and-seek.mdx
+  - api: API Reference
+```
+
+<Card title="Voir en action" icon="eye" href="/learn/docs/customization/hidden-page">
+Cette page est masquée de la barre latérale et des moteurs de recherche, mais vous pouvez y accéder par lien direct.
+</Card>
+
+### Exclue de la recherche uniquement
+
+Définissez `noindex: true` dans le frontmatter d'une page pour l'exclure des moteurs de recherche et de [llms.txt](/learn/docs/ai-features/llms-txt) tout en la gardant découvrable sur votre site. Ceci est utile pour la documentation en accès anticipé ou le contenu que vous souhaitez que les lecteurs trouvent via la navigation mais pas via la recherche ou les outils IA.
+
+```mdx title="early-access-feature.mdx" {3}
+---
+title: Fonctionnalité en accès anticipé
+noindex: true
+---
+```
+
+Pour plus d'options liées au SEO, consultez [Métadonnées SEO](/learn/docs/seo/setting-seo-metadata).
+
+## Masquer un endpoint API
+
+Définissez `hidden: true` dans la configuration de mise en page de l'endpoint dans `docs.yml` pour le masquer de la barre latérale. Comme pour `hidden` au niveau de la page, les endpoints masqués sont automatiquement exclus de l'indexation des moteurs de recherche, il n'est donc pas nécessaire de définir `noindex: true`.
+
+```yaml title="docs.yml" {6}
+navigation:
+  - api: API Reference
+    layout:
+      - plants:
+          - endpoint: POST /plants/{plantId}
+            hidden: true
+```
+
+Pour les détails complets de configuration, y compris des exemples pour OpenAPI, Fern Definition et les endpoints WebSocket, consultez [Masquer des endpoints](/learn/docs/api-references/customize-api-reference-layout#hiding-endpoints).
+
+## Masquer une section ou une version
+
+Masquez une section entière ou une version de la barre latérale — par exemple, une version d'API héritée ou une section de documentation d'outils internes.
+
+Contrairement au masquage d'une page ou d'un endpoint, masquer une section ou une version ne supprime que le groupe de la barre latérale. Les pages individuelles qu'elle contient restent indexées par les moteurs de recherche et l'IA car `hidden` s'applique au regroupement de la section, pas à chaque page. Pour exclure également les pages individuelles des résultats de recherche, ajoutez `noindex: true` au frontmatter de chaque page.
+
+<Tabs>
+<Tab title="Section masquée">
+```yaml title="docs.yml" {8}
+navigation:
+  - section: Introduction
+    contents:
+      - page: My Page
+        path: ./pages/my-page.mdx
+  - api: API Reference
+  - section: Hidden Section
+    hidden: true
+    contents:
+      - page: Hide and Seek
+        path: ./pages/hide-and-seek.mdx
+```
+
+<Frame>
+<img src="hidden-section.png" alt="Un site avec une section masquée" />
+</Frame>
+</Tab>
+<Tab title="Version masquée">
+```yaml title="docs.yml" {8}
+versions:
+  - display-name: v3
+    path: ./versions/v3.yml
+  - display-name: v2
+    path: ./versions/v2.yml
+  - display-name: v1 (Legacy)
+    path: ./versions/v1.yml
+    hidden: true
+```
+
+<Info>La version par défaut (la première version de votre liste `versions`) ne peut pas être masquée.</Info>
+</Tab>
+</Tabs>