Déclarer la section

Une référence est une section générée : une source nomme un artefact et le type qui le lit, et les pages en découlent.

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. 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é.

{
  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. 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.