搜尋
首頁web前端js教程使用 Rapi Doc 和 Vitepress 建立優雅的 OpenAPI 規範文檔

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

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

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

Create elegant OpenAPI spec documentation with Rapi Doc and Vitepress

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

所以我選了 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></rapidoc>

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

我得到了這個:

Create elegant OpenAPI spec documentation with Rapi Doc and Vitepress

我的瀏覽器凍結了。

哇哦,無限循環萬歲!

發生了什麼事? 所以,由於 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「嘿,這個標籤是禁止的」。

所以,我們有了它,它運行了!

Create elegant OpenAPI spec documentation with Rapi Doc and Vitepress

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

建立應用程式

我執行了yarn docs:build 指令。我立刻(哇,Vite,你太快了!)收到了這個錯誤:

Create elegant OpenAPI spec documentation with Rapi Doc and Vitepress

此錯誤表示在建置期間,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></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 文件!

Create elegant OpenAPI spec documentation with Rapi Doc and Vitepress

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

陳述
本文內容由網友自願投稿,版權歸原作者所有。本站不承擔相應的法律責任。如發現涉嫌抄襲或侵權的內容,請聯絡admin@php.cn
使用Next.js(後端集成)構建多租戶SaaS應用程序使用Next.js(後端集成)構建多租戶SaaS應用程序Apr 11, 2025 am 08:23 AM

我使用您的日常技術工具構建了功能性的多租戶SaaS應用程序(一個Edtech應用程序),您可以做同樣的事情。 首先,什麼是多租戶SaaS應用程序? 多租戶SaaS應用程序可讓您從唱歌中為多個客戶提供服務

如何使用Next.js(前端集成)構建多租戶SaaS應用程序如何使用Next.js(前端集成)構建多租戶SaaS應用程序Apr 11, 2025 am 08:22 AM

本文展示了與許可證確保的後端的前端集成,並使用Next.js構建功能性Edtech SaaS應用程序。 前端獲取用戶權限以控制UI的可見性並確保API要求遵守角色庫

JavaScript:探索網絡語言的多功能性JavaScript:探索網絡語言的多功能性Apr 11, 2025 am 12:01 AM

JavaScript是現代Web開發的核心語言,因其多樣性和靈活性而廣泛應用。 1)前端開發:通過DOM操作和現代框架(如React、Vue.js、Angular)構建動態網頁和單頁面應用。 2)服務器端開發:Node.js利用非阻塞I/O模型處理高並發和實時應用。 3)移動和桌面應用開發:通過ReactNative和Electron實現跨平台開發,提高開發效率。

JavaScript的演變:當前的趨勢和未來前景JavaScript的演變:當前的趨勢和未來前景Apr 10, 2025 am 09:33 AM

JavaScript的最新趨勢包括TypeScript的崛起、現代框架和庫的流行以及WebAssembly的應用。未來前景涵蓋更強大的類型系統、服務器端JavaScript的發展、人工智能和機器學習的擴展以及物聯網和邊緣計算的潛力。

神秘的JavaScript:它的作用以及為什麼重要神秘的JavaScript:它的作用以及為什麼重要Apr 09, 2025 am 12:07 AM

JavaScript是現代Web開發的基石,它的主要功能包括事件驅動編程、動態內容生成和異步編程。 1)事件驅動編程允許網頁根據用戶操作動態變化。 2)動態內容生成使得頁面內容可以根據條件調整。 3)異步編程確保用戶界面不被阻塞。 JavaScript廣泛應用於網頁交互、單頁面應用和服務器端開發,極大地提升了用戶體驗和跨平台開發的靈活性。

Python還是JavaScript更好?Python還是JavaScript更好?Apr 06, 2025 am 12:14 AM

Python更适合数据科学和机器学习,JavaScript更适合前端和全栈开发。1.Python以简洁语法和丰富库生态著称,适用于数据分析和Web开发。2.JavaScript是前端开发核心,Node.js支持服务器端编程,适用于全栈开发。

如何安裝JavaScript?如何安裝JavaScript?Apr 05, 2025 am 12:16 AM

JavaScript不需要安裝,因為它已內置於現代瀏覽器中。你只需文本編輯器和瀏覽器即可開始使用。 1)在瀏覽器環境中,通過標籤嵌入HTML文件中運行。 2)在Node.js環境中,下載並安裝Node.js後,通過命令行運行JavaScript文件。

在Quartz中如何在任務開始前發送通知?在Quartz中如何在任務開始前發送通知?Apr 04, 2025 pm 09:24 PM

如何在Quartz中提前發送任務通知在使用Quartz定時器進行任務調度時,任務的執行時間是由cron表達式設定的。現�...

See all articles

熱AI工具

Undresser.AI Undress

Undresser.AI Undress

人工智慧驅動的應用程序,用於創建逼真的裸體照片

AI Clothes Remover

AI Clothes Remover

用於從照片中去除衣服的線上人工智慧工具。

Undress AI Tool

Undress AI Tool

免費脫衣圖片

Clothoff.io

Clothoff.io

AI脫衣器

AI Hentai Generator

AI Hentai Generator

免費產生 AI 無盡。

熱門文章

R.E.P.O.能量晶體解釋及其做什麼(黃色晶體)
3 週前By尊渡假赌尊渡假赌尊渡假赌
R.E.P.O.最佳圖形設置
3 週前By尊渡假赌尊渡假赌尊渡假赌
R.E.P.O.如果您聽不到任何人,如何修復音頻
3 週前By尊渡假赌尊渡假赌尊渡假赌
WWE 2K25:如何解鎖Myrise中的所有內容
3 週前By尊渡假赌尊渡假赌尊渡假赌

熱工具

VSCode Windows 64位元 下載

VSCode Windows 64位元 下載

微軟推出的免費、功能強大的一款IDE編輯器

SublimeText3 英文版

SublimeText3 英文版

推薦:為Win版本,支援程式碼提示!

禪工作室 13.0.1

禪工作室 13.0.1

強大的PHP整合開發環境

mPDF

mPDF

mPDF是一個PHP庫,可以從UTF-8編碼的HTML產生PDF檔案。原作者Ian Back編寫mPDF以從他的網站上「即時」輸出PDF文件,並處理不同的語言。與原始腳本如HTML2FPDF相比,它的速度較慢,並且在使用Unicode字體時產生的檔案較大,但支援CSS樣式等,並進行了大量增強。支援幾乎所有語言,包括RTL(阿拉伯語和希伯來語)和CJK(中日韓)。支援嵌套的區塊級元素(如P、DIV),

SublimeText3 Mac版

SublimeText3 Mac版

神級程式碼編輯軟體(SublimeText3)