Une référence est une [section générée](/concepts/generated-sections) : une source
nomme un artefact et le type qui le lit, et les pages en découlent.

```ts
export default defineAppConfig({
  duxt: {
    sources: [
      {
        path: 'docs',
        generated: [
          {
            type: 'openapi',
            path: 'openapi.yaml',
            label: 'API'
          }
        ]
      }
    ]
  }
})
```

Les champs qu’une déclaration prend sont les mêmes pour tous les types et se
trouvent dans [Sources](/reference/sources). `openapi` ne nomme
aucune option propre ; ce à quoi il répond est ci-dessous.

## Ce qu’elle construit

```
/api                      la vue d’ensemble, depuis `info`
/api/<tag>                une page par étiquette
/api/<tag>/<operation>    une page par opération, avec le client
```

Une opération sans étiquette tombe dans un groupe par défaut, et les webhooks 3.1
dans un groupe à eux — un webhook est le même objet sous un nom au lieu d’une URL,
il se rend donc par la même page et dit ce qu’il est.

## Versionnage

**Par version.** La description d’une API appartient à la release qu’elle décrit :
`v1` et `v2` ont des endpoints différents, et à un lecteur sur `v1` qui demande ce
que signifie un champ, il ne faut pas montrer la réponse de `v2`. Chaque
collection de version porte le document à sa propre ref, et le sélecteur de
versions agit sur la référence exactement comme sur la prose.

C’est l’inverse de ce que fait le type `changelog`, et la raison pour laquelle le
versionnage est une politique du type et non une règle de la couche.

## Localisation

**Par langue, là où une langue fournit un document à elle.** Une description est
de la prose écrite autant qu’une structure — résumés, descriptions de champs, sens
des réponses — une version traduite est donc un artefact réel et non le même
fichier réétiqueté.

```ts
{
  type: 'openapi',
  path: 'openapi.yaml',
  label: 'API',
  locales: { de: 'openapi.de.yaml' }
}
```

Une langue absente de la table ne construit aucune collection, et la chaîne de
repli existante lui sert la référence de la langue par défaut, avec la bannière de
traduction qui le dit — voir [Localisation](/concepts/localisation). Ce qui reste
traduit dans tous les cas, ce sont **les libellés propres à la couche** — les
en-têtes de tableau, « Request », « Response », les noms de statut — car ceux-là
appartiennent au thème et non au document.

## Quand le document ne peut pas être lu

Le build échoue, et dit quelle section et pourquoi. C’est délibéré : une référence
devenue silencieusement une section vide est une référence dont personne ne
remarque la disparition.