Cipta dokumentasi spesifikasi OpenAPI yang elegan dengan Rapi Doc dan Vitepress

Baru-baru ini saya terpaksa membuat halaman dokumentasi yang menyokong dokumentasi spesifikasi OpenAPI. Apakah dokumentasi spesifikasi OpenAPI? Halaman, sama ada dihoskan sendiri atau disertakan dalam platform pengurusan API anda, yang membolehkan pengguna menyemak titik akhir, kaedah, webhook, dll., yang tersedia berdasarkan OpenAPI JSON atau YAML.

Saya perlu mencari keseimbangan antara memerlukan sebanyak mungkin pilihan penyesuaian dan menggunakan alatan sedia untuk digunakan untuk persediaan dan penggunaan pantas.

Dan saya menemui Rapi Doc - komponen web yang boleh dibenamkan di mana-mana sahaja.

Dengan komponen sedia, saya memerlukan alat untuk menulis dokumentasi yang menyokong komponen tersuai.

Jadi saya memilih Vitepress. Dan saya mempunyai dua alat yang saya ingin gabungkan. Bagaimana keadaannya? Jom ketahui.

Menjalankan apl dalam mod pembangun

Saya akan melangkau cerita persediaan Vitepress - anda boleh mendapatkan arahan pada halaman utama mereka.

Saya turut mencipta komponen RapiDoc.vue tersuai tempat saya membenamkan komponen web rapi-doc saya.

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

Saya juga membenamkan komponen tersuai ini dalam halaman api-docs.md (ya, anda boleh membenamkan Komponen Vue dalam Markdown, saya suka Vitepress untuknya!) supaya saya dapat melihatnya dalam dokumentasi Vitepress saya .

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

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

<RapiDoc />

Saya menjalankan yarn docs:dev mengharapkan segala-galanya berjalan lancar (saya mengikut arahan daripada kedua-dua dokumentasi, jadi ia sepatutnya baik, bukan?)...

Dan saya mendapat ini:

Dan penyemak imbas saya membeku.

Woohoo, hidup gelung yang tidak terhingga!

Apa yang berlaku? Jadi, memandangkan rapi-doc ialah komponen web, saya perlu memberitahu pengkompil Vue secara eksplisit untuk tidak menghuraikannya. Untuk membiarkan sahaja.

Dan di dalam fail config.mts saya, saya perlu menambah:

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

Kami hanya perlu menyemak elemen tersuai dan memaklumkan Vue "hey, teg ini di luar had".

Jadi, kami ada, ia berjalan!

Dan kemudian saya cuba membinanya supaya saya boleh menyediakan penempatan.

Membina apl

Saya menjalankan perintah yarn docs:build. Dan saya serta-merta (wah, Vite, anda cepat!) mendapat ralat ini:

Ralat ini bermakna semasa masa bina, Vite tidak dapat mengakses harta sendiri. Ini juga boleh berlaku jika anda cuba mengakses API penyemak imbas (cth., tetingkap) daripada pelayan (dalam Nuxt atau mana-mana rangka kerja SSR lain, contohnya).

Jadi apa yang boleh kita lakukan? Kami boleh mengimportnya secara dinamik dalam masa jalan!

Jom tukar import kami daripada ini:

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

Untuk ini:

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

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

<RapiDoc />

Dan kini binaan harus lulus tanpa sebarang masalah! Nikmati dokumen spesifikasi API anda!

Bonus: Mod Gelap

Vitepress datang dengan mod gelap, berfungsi di luar kotak. Tetapi bagaimanakah kami boleh membuat dokumentasi RapiDoc kami bertindak balas terhadap perubahan mod?

Kita boleh menggunakan Vitepress core composable - useData. Ia mengandungi sifat isDark dengan maklumat jika mod gelap didayakan atau tidak.

Jadi mari kita gunakannya di dalam bahagian skrip dalam 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;
        }
      }
    }
  },
})

Sekarang apabila kita mempunyai rujukan tema, kita boleh menghantarnya ke Komponen Web rapi-doc melalui pengikatan atribut:

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

Kita perlu menambah satu perkara lagi untuk mod gelap berfungsi dengan betul - bertindak balas terhadap perubahan tema.

Jom tambah pemerhati pada bahagian skrip kami:

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

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

Dan voila, anda telah mencipta dokumen API yang bertindak balas terhadap perubahan tema!

Atas ialah kandungan terperinci Cipta dokumentasi spesifikasi OpenAPI yang elegan dengan Rapi Doc dan Vitepress. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!