update-api-docs

API ドキュメントの更新

このスキルでは、本番環境の OpenAPI 仕様から API リファレンスドキュメントを更新する方法を説明します。

概要

API ドキュメントは、docusaurus-plugin-openapi-docs を使用して OpenAPI 仕様から生成されます。ワークフローは次のとおりです。

1. 本番環境から最新の openapi.json をダウンロードする
2. ローカルの仕様ファイルを置き換える
3. API ドキュメントのページを再生成する

ファイルの場所

用途	パス
OpenAPI 仕様（ソース）	docs/docs/reference/openapi.json
生成された API ドキュメント	docs/docs/reference/api/*.api.mdx
生成されたサイドバー	docs/docs/reference/api/sidebar.ts
Docusaurus 設定	docs/docusaurus.config.ts

手順

1. 更新スクリプトを実行する

docs/scripts/update-api-docs.sh にあるラッパースクリプトは、OpenAPI 仕様をダウンロードし、ローカルファイルを置き換えて、ドキュメントを一度に再生成します。

cd docs

# Default — fetch from production (live cloud API)
pnpm update-api-docs

# Explicit live cloud API
pnpm update-api-docs:live

# From a locally running API (http://localhost/api/openapi.json)
pnpm update-api-docs:local

# From an explicit local file
pnpm update-api-docs:file /path/to/openapi.json

このスクリプトは仕様を docs/docs/reference/openapi.json に書き込み、その後 npm run clean-api-docs -- agenta に続けて npm run gen-api-docs -- agenta を実行します。agenta 引数は、docusaurus.config.ts で定義された OpenAPI 設定 ID を指します。

2. 依存関係をインストールする（必要な場合）

新しくクローンした場合や、依存関係をまだインストールしていない場合は、次を実行します。

cd docs
npm install

次のファイルが生成されます。

• 各エンドポイントの .api.mdx ファイル
• API カテゴリの .tag.mdx ファイル
• ナビゲーション用の sidebar.ts

5. 変更を確認する

必要に応じて、開発サーバーを起動してプレビューします。

cd docs
npm run start

次に http://localhost:5000/docs/reference/api にアクセスして、API ドキュメントが正しく表示されることを確認します。

コミットのガイドライン

これらの変更をコミットする際は、次のようにします。

1. 最初のコミット - API ドキュメントの更新：

   docs(api): update OpenAPI spec from production
   

2. 変更したファイルをすべて含めます。

   • docs/docs/reference/openapi.json
   • docs/docs/reference/api/*.api.mdx
   • docs/docs/reference/api/*.tag.mdx
   • docs/docs/reference/api/sidebar.ts

トラブルシューティング

「missing required argument 'id'」エラー

clean コマンドと generate コマンドには設定 ID が必要です。次を使用してください。

npm run clean-api-docs -- agenta
npm run gen-api-docs -- agenta

「docusaurus: not found」エラー

まず docs/ ディレクトリで npm install を実行してください。

onBrokenMarkdownLinks に関する非推奨警告

これは既知の警告であり、安全に無視できます。今後の Docusaurus v4 への移行時に対処される予定です。

関連する設定

OpenAPI プラグインは docs/docusaurus.config.ts で設定されています。

[
  "docusaurus-plugin-openapi-docs",
  {
    id: "openapi",
    docsPluginId: "classic",
    config: {
      agenta: {
        specPath: "docs/reference/openapi.json",
        outputDir: "docs/reference/api",
        downloadUrl: "https://raw.githubusercontent.com/Agenta-AI/agenta/refs/heads/main/docs/docs/reference/openapi.json",
        sidebarOptions: {
          groupPathsBy: "tag",
          categoryLinkSource: "tag",
        },
      },
    },
  },
],