Rapi Doc と Vitepress を使用してエレガントな OpenAPI 仕様ドキュメントを作成する

最近、OpenAPI 仕様ドキュメントをサポートするドキュメント ページを作成する必要がありました。 OpenAPI 仕様ドキュメントとは何ですか?自己ホストされているか、API 管理プラットフォームに含まれているページ。ユーザーは、このページを使用して、OpenAPI JSON または YAML に基づいてどのエンドポイント、メソッド、Webhook などが使用できるかを確認できます。

できるだけ多くのカスタマイズ オプションが必要なことと、すぐに使用できるツールを使用して迅速なセットアップと展開を行うこととの間のバランスを見つける必要がありました。

そして、どこにでも埋め込むことができる Web コンポーネントである Rapi Doc を見つけました。

コンポーネントの準備ができたら、カスタム コンポーネントをサポートするドキュメントを作成するツールが必要になりました。

そこで私は Vitepress を選びました。そして、統合したいツールが 2 つありました。どうでしたか？調べてみましょう。

開発モードでアプリを実行する

Vitepress のセットアップの話は省略します。手順はメイン ページにあります。

また、rapi-doc Web コンポーネントを埋め込んだカスタム RapiDoc.vue コンポーネントも作成しました。

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

テーマ ref を取得したら、属性バインディングを介してそれを rapi-doc Web コンポーネントに渡すことができます。

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

ダークモードが正しく動作するには、テーマの変更に対応するということをもう 1 つ追加する必要があります。

スクリプト セクションにウォッチャーを追加しましょう:

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

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

これで、テーマの変更に対応する API ドキュメントが作成されました!

以上がRapi Doc と Vitepress を使用してエレガントな OpenAPI 仕様ドキュメントを作成するの詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。