Erstellen Sie elegante OpenAPI-Spezifikationsdokumentation mit Rapi Doc und Vitepress

Ich musste kürzlich eine Dokumentationsseite erstellen, die die OpenAPI-Spezifikationsdokumentation unterstützt. Was ist eine OpenAPI-Spezifikationsdokumentation? Eine Seite, entweder selbst gehostet oder in Ihrer API-Verwaltungsplattform enthalten, auf der Benutzer überprüfen können, welche Endpunkte, Methoden, Webhooks usw. basierend auf OpenAPI JSON oder YAML verfügbar sind.

Ich musste ein Gleichgewicht zwischen der Notwendigkeit möglichst vieler Anpassungsoptionen und der Verwendung sofort einsatzbereiter Tools für eine schnelle Einrichtung und Bereitstellung finden.

Und ich habe Rapi Doc gefunden – eine Webkomponente, die überall eingebettet werden kann.

Da die Komponente fertig war, brauchte ich ein Tool zum Schreiben einer Dokumentation, die benutzerdefinierte Komponenten unterstützt.

Also habe ich mich für Vitepress entschieden. Und ich hatte zwei Tools, die ich zusammenführen wollte. Wie ist es gelaufen? Finden wir es heraus.

App im Entwicklungsmodus ausführen

Ich überspringe die Geschichte der Vitepress-Einrichtung – Sie finden die Anweisungen auf der Hauptseite.

Ich habe außerdem eine benutzerdefinierte RapiDoc.vue-Komponente erstellt, in die ich meine Rapi-Doc-Webkomponente eingebettet habe.

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

Ich habe diese benutzerdefinierte Komponente auch in eine api-docs.md-Seite eingebettet (Ja, Sie können Vue-Komponenten in Markdown einbetten, ich liebe Vitepress dafür!)damit ich sie in meiner Vitepress-Dokumentation sehen konnte .

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

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

<RapiDoc />

Ich habe „garn docs:dev“ ausgeführt und erwartet, dass alles reibungslos verläuft (ich habe die Anweisungen beider Dokumentationen befolgt, also sollte es in Ordnung sein, oder?)...

Und ich habe das:

Und mein Browser ist eingefroren.

Woohoo, es lebe die Endlosschleife!

Was ist passiert? Da es sich bei rapi-doc um eine Webkomponente handelt, muss ich den Vue-Compiler explizit anweisen, es nicht zu analysieren. Es einfach in Ruhe lassen.

Und in meiner config.mts-Datei musste ich Folgendes hinzufügen:

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;
        }
      }
    }
  },
})

Wir müssen nur nach benutzerdefinierten Elementen suchen und Vue informieren: „Hey, dieses Tag ist tabu.“

So, wir haben es, es läuft!

Und dann habe ich versucht, es zu erstellen, damit ich die Bereitstellung einrichten konnte.

Erstellen der App

Ich habe den Befehl „garn docs:build“ ausgeführt. Und ich bekam sofort (wow, Vite, du bist schnell!) diesen Fehler:

Dieser Fehler bedeutet, dass Vite während der Erstellungszeit nicht auf eine Selbsteigenschaft zugreifen konnte. Dies kann auch passieren, wenn Sie versuchen, vom Server aus auf die Browser-API (z. B. Fenster) zuzugreifen (z. B. in Nuxt oder einem anderen SSR-Framework).

Was können wir also tun? Wir können es dynamisch zur Laufzeit importieren!

Ändern wir unseren Import hiervon:

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

Dazu:

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

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

<RapiDoc />

Und jetzt sollte der Build ohne Probleme verlaufen! Viel Spaß mit den API-Spezifikationsdokumenten!

Bonus: Dunkler Modus

Vitepress verfügt über einen Dunkelmodus, der sofort einsatzbereit ist. Aber wie können wir dafür sorgen, dass unsere RapiDoc-Dokumentation auf Modusänderungen reagiert?

Wir können Vitepress Core Composable verwenden – useData. Es enthält die Eigenschaft isDark mit Informationen darüber, ob der Dunkelmodus aktiviert ist oder nicht.

Also verwenden wir es im Skriptabschnitt im 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;
        }
      }
    }
  },
})

Wenn wir nun eine Theme-Referenz haben, können wir sie über die Attributbindung an die rapi-doc-Webkomponente übergeben:

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

Wir müssen noch etwas hinzufügen, damit der Dunkelmodus richtig funktioniert – auf Themenänderungen reagieren.

Fügen wir einen Beobachter zu unserem Skriptabschnitt hinzu:

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

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

Und voilà, Sie haben API-Dokumente erstellt, die auf Designänderungen reagieren!

Das obige ist der detaillierte Inhalt vonErstellen Sie elegante OpenAPI-Spezifikationsdokumentation mit Rapi Doc und Vitepress. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!