使用 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中文网其他相关文章！