使用 Rapi Doc 和 Vitepress 建立優雅的 OpenAPI 規範文檔

我最近必須建立一個支援 OpenAPI 規範文件的文件頁面。什麼是 OpenAPI 規範文件？自託管或包含在 API 管理平台中的頁面，允許使用者基於 OpenAPI JSON 或 YAML 檢查哪些端點、方法、Webhook 等可用。

我需要在需要盡可能多的自訂選項與使用現成工具進行快速設定和部署之間找到平衡。

我發現了 Rapi Doc - 一個可以嵌入到任何地方的 Web 元件。

元件準備就緒後，我需要一個工具來編寫支援自訂元件的文件。

所以我選了 Vitepress。我有兩個想要合併的工具。進展如何？讓我們來看看。

在開發模式下運行應用程式

我將跳過 Vitepress 設定的故事 - 您可以在他們的主頁上找到說明。

我還建立了一個自訂 RapiDoc.vue 元件，其中嵌入了我的 Rapi-doc Web 元件。

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

我還在api-docs.md 頁面中嵌入了這個自訂元件（是的，您可以在Markdown 中嵌入Vue 元件，我喜歡Vitepress！） 所以我可以在我的Vitepress文檔中看到它.

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

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

<RapiDoc />

我運行了yarn docs:dev，希望一切順利（我按照兩個文檔中的說明進行操作，所以應該沒問題，對吧？）...

我得到了這個：

我的瀏覽器凍結了。

哇哦，無限循環萬歲！

發生了什麼事？ 所以，由於 rapi-doc 是一個 Web 元件，我需要明確告訴 Vue 編譯器不要解析它。就這樣吧。

在我的 config.mts 檔案中我需要新增：

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

我們只需要檢查自訂元素並通知 Vue「嘿，這個標籤是禁止的」。

所以，我們有了它，它運行了！

然後我嘗試建置它，以便我可以設定部署。

建立應用程式

我執行了yarn docs:build 指令。我立刻（哇，Vite，你太快了！）收到了這個錯誤：

此錯誤表示在建置期間，Vite 無法存取 self 屬性。如果您嘗試從伺服器（例如在 Nuxt 或任何其他 SSR 框架中）存取瀏覽器 API（例如視窗），也可能會發生這種情況。

那我們能做什麼呢？我們可以在運行時動態導入它！

讓我們改變導入：

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

對此：

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

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

<RapiDoc />

現在建造應該可以順利通過了！享受 API 規格文件！

獎勵：黑暗模式

Vitepress 配備深色模式，開箱即用。但是我們怎麼能讓我們的 RapiDoc 文件對模式變化做出反應呢？

我們可以使用 Vitepress 核心可組合項目 - useData。它包含 isDark 屬性，其中包含是否啟用深色模式的資訊。

所以讓我們在 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;
        }
      }
    }
  },
})

現在，當我們有了主題引用時，我們可以透過屬性綁定將其傳遞給 rapi-doc Web 元件：

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

我們還需要添加一件事才能使深色模式正常工作 - 響應主題更改。

讓我們為腳本部分新增一個觀察者：

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

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

瞧，您建立了對主題變更做出反應的 API 文件！

以上是使用 Rapi Doc 和 Vitepress 建立優雅的 OpenAPI 規範文檔的詳細內容。更多資訊請關注PHP中文網其他相關文章！