Créez une documentation élégante sur les spécifications OpenAPI avec Rapi Doc et Vitepress

J'ai récemment dû créer une page de documentation prenant en charge la documentation des spécifications OpenAPI. Qu'est-ce qu'une documentation sur les spécifications OpenAPI ? Une page, auto-hébergée ou incluse dans votre plateforme de gestion d'API, qui permet aux utilisateurs de vérifier quels points de terminaison, méthodes, webhooks, etc., sont disponibles sur la base d'OpenAPI JSON ou YAML.

Je devais trouver un équilibre entre le besoin d'autant d'options de personnalisation que possible et l'utilisation d'outils prêts à l'emploi pour une configuration et un déploiement rapides.

Et j'ai trouvé Rapi Doc - un composant Web qui peut être intégré n'importe où.

Une fois le composant prêt, j'avais besoin d'un outil pour rédiger une documentation prenant en charge les composants personnalisés.

J'ai donc choisi Vitepress. Et j'avais deux outils que je voulais fusionner. Comment ça s'est passé ? Découvrons-le.

Exécuter l'application en mode développement

Je vais sauter l'histoire de la configuration de Vitepress - vous pouvez trouver les instructions sur leur page principale.

J'ai également créé un composant RapiDoc.vue personnalisé dans lequel j'ai intégré mon composant Web rapi-doc.

<script setup>
import 'rapidoc'
</script>

<template>
<div>
  <rapi-doc
      spec-url = "https://petstore.swagger.io/v2/swagger.json"
      render-style = "read"
      style = "height:100vh; width:100%"
  > </rapi-doc>
</div>
</template>

<style scoped>

</style>

J'ai également intégré ce composant personnalisé dans une page api-docs.md (oui, vous pouvez intégrer des composants Vue dans Markdown, j'adore Vitepress pour cela !) pour pouvoir le voir dans ma documentation Vitepress .

---
sidebar: false
layout: page
---

<script setup>
import RapiDoc from './components/RapiDoc.vue';
</script>

<RapiDoc />

J'ai exécuté Yarn docs:dev en m'attendant à ce que tout se passe bien (j'ai suivi les instructions des deux documentations, donc ça devrait aller, non ?)...

Et j'ai eu ça :

Et mon navigateur s'est bloqué.

Woohoo, vive la boucle infinie !

Que s'est-il passé ? Ainsi, puisque rapi-doc est un composant Web, je dois explicitement dire au compilateur Vue de ne pas l'analyser. Pour le laisser tranquille.

Et dans mon fichier config.mts, je devais ajouter :

import { defineConfig } from 'vitepress'

// https://vitepress.dev/reference/site-config
export default defineConfig({
  ...
  vue: {
    template: {
      compilerOptions: {
        isCustomElement: (tag: string) => {
          return tag.indexOf('rapi-doc') >= 0;
        }
      }
    }
  },
})

Nous devons juste vérifier les éléments personnalisés et informer Vue "hé, cette balise est interdite".

Alors, on l'a, ça marche !

Et puis j'ai essayé de le construire pour pouvoir configurer le déploiement.

Construire l'application

J'ai exécuté la commande Yarn Docs:build. Et j'ai immédiatement (wow, Vite, tu es rapide !) j'ai eu cette erreur :

Cette erreur signifie que pendant la construction, Vite n'a pas pu accéder à une propriété personnelle. Cela peut également se produire si vous essayez d'accéder à l'API du navigateur (par exemple, une fenêtre) à partir du serveur (dans Nuxt ou tout autre framework SSR, par exemple).

Alors, que pouvons-nous faire ? Nous pouvons l'importer dynamiquement au runtime !

Changeons notre importation à partir de ceci :

<script setup>
import 'rapidoc'
</script>

<template>
<div>
  <rapi-doc
      spec-url = "https://petstore.swagger.io/v2/swagger.json"
      render-style = "read"
      style = "height:100vh; width:100%"
  > </rapi-doc>
</div>
</template>

<style scoped>

</style>

À ceci :

---
sidebar: false
layout: page
---

<script setup>
import RapiDoc from './components/RapiDoc.vue';
</script>

<RapiDoc />

Et maintenant, la construction devrait se dérouler sans problème ! Profitez de vos documents de spécifications API !

Bonus : mode sombre

Vitepress est livré avec un mode sombre, qui fonctionne immédiatement. Mais comment pouvons-nous faire en sorte que notre documentation RapiDoc réagisse aux changements de mode ?

Nous pouvons utiliser le noyau composable Vitepress - useData. Il contient la propriété isDark avec des informations si le mode sombre est activé ou non.

Utilisons-le donc dans la section script du SFC :

import { defineConfig } from 'vitepress'

// https://vitepress.dev/reference/site-config
export default defineConfig({
  ...
  vue: {
    template: {
      compilerOptions: {
        isCustomElement: (tag: string) => {
          return tag.indexOf('rapi-doc') >= 0;
        }
      }
    }
  },
})

Maintenant, lorsque nous avons une référence de thème, nous pouvons la transmettre au composant Web rapi-doc via la liaison d'attribut :

<script setup>
import 'rapidoc';
</script>

Nous devons ajouter une chose supplémentaire pour que le mode sombre fonctionne correctement : répondre au changement de thème.

Ajoutons un observateur à notre section script :

<script setup>
import { onMounted } from 'vue';

onMounted(() => {
  import('rapidoc');
});
</script>

Et voilà, vous avez créé des documents API qui réagissent aux changements de thème !

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!