--- title: API リファレンスサイドバー slug: MDN/Contribute/Howto/Write_an_API_reference/Sidebars tags: - API - Documentation - Guide - MDN - MDN Meta - Reference - groupdata - metadata - onboarding - sidebars translation_of: MDN/Structures/API_references/API_reference_sidebars original_slug: MDN/Structures/API_references/API_reference_sidebars ---
{{MDNSidebar}}

API リファレンスページにカスタムサイドバーを追加して、関連するインターフェイス、チュートリアル、およびその API に関連する他のリソースへのリンクを表示することができます。この記事ではその方法を説明します。

サイドバーの作成

API サイドバーを作成するには、次の3つの手順を実行する必要があります。

  1. API リファレンスページを作成します
  2. 特定の API の項目を KumaScript リポジトリの GroupData.json データファイルに追加します
  3. {{TemplateLink("APIRef")}} マクロを使用して、表示したい各ページにサイドバーを挿入します

これらのステップを順番に実行しましょう。この記事で参照する例は、Fetch API です。

API リファレンスページの作成

サイドバーをページに追加する前に、ページ自体を作成する必要があります (詳細については、API リファレンスに必要なものガイドを参照してください)。

GroupData.json への項目の追加

GroupData.json ファイルには、API 参照サイドバーに表示されるリンクに関するすべてのデータが格納されます。呼び出されると、{{TemplateLink("APIRef")}} マクロは引数として与えられた API 名を取り、GroupData.json でその名前を検索し、適切なサイドバーを作成してページに挿入します。

GroupData.json に項目を追加するには、以下を行う必要があります。

  1. GitHub アカウントを持っていることを確認します
  2. KumaScript リポジトリをフォークし、新しいブランチを作成して変更を保存し、リポジトリをローカルにクローンします
  3. 作業を開始する前に新しいブランチをチェックアウトし、作業が終わったら変更を押してください
  4. プルリクエストを作成して、MDN チームがあなたの作業をレビューし、必要に応じて変更を求めることができるようにします

GitHub の使用についてサポートが必要な場合は、互換性一覧表に詳細なガイドがあります。

GroupData.json ファイルは、KumaScript リポジトリの macros ディレクトリ内にあります。それを見ると、巨大な JSON 構造があり、それぞれの API に独自のメンバーがあります。名前は API 名で、値は生成するサイドバーリンクを定義するいくつかのサブメンバーを含むオブジェクトです。

たとえば、MDN の Fetch API ページを見てください。 GroupData.json の対応する項目は次のようになります。

"Fetch API": {
    "overview":   [ "Fetch API"],
    "interfaces": [ "Body",
                    "Headers",
                    "Request",
                    "Response",
                    "FetchController",
                    "FetchObserver",
                    "FetchSignal",
                    "ObserverCallback" ],
    "methods":    [ "WindowOrWorkerGlobalScope.fetch()" ],
    "properties": [],
    "events":     []
},

ご覧のとおり、名前には "Fetch API" を使用し、オブジェクト値の内側には多数のサブメンバーが含まれています。

GroupData 項目内に含めるサブメンバー

この節では、GroupData 項目に含めることができるすべてのサブメンバーを一覧表示します。

リストされたサブメンバーの中に含まれる値のほとんどは、リンクテキストと、表示されるリンクの最終的な URL を生成するためのメイン API インデックスページ — /<language-code>/docs/Web/API — の最後に追加されたスラッグの両方に相当することに注意してください。そのため、例えば "Body" とすると、 en-US ロケールではこのようなリンクが生成されます。

<li><a href="https://developer.mozilla.org/en-US/docs/Web/API">Body</a></li>

いくつかの例外があります。例えば "guides" サブメンバーには、関連するガイド/チュートリアルへのリンクを定義するリンク情報 (タイトルとスラッグ) が1つ以上含まれています。この場合、スラッグは MDN の docs ルート — https://developer.mozilla.org/<language-code>/docs — の最後に追加され、MDN のどこにでも記事を含めることができます。

以下が利用可能なメンバーです。それぞれの場合、ロケールが en-US であると仮定した例が含まれています。これらはすべて技術的にはオプションですが、これらを省略する代わりに空の配列を含めることを強く推奨します。

  1. "overview" — 値は配列で、 API 概要ページがあればその中にスラッグを含めます。"Fetch API" の場合、 https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API へのリンクが生成されます。

  2. "interfaces" — 値は配列で、その API の一部を構成するすべてのインターフェイスをリストアップする必要があります。 "Body" の場合は https://developer.mozilla.org/en-US/docs/Web/API/Body へのリンクが生成されます。

  3. "methods" — 値は、 {{domxref("Navigator")}} や {{domxref("Window")}} で生成されたインスタンス化メソッドなど、仕様が他の API に関連付けられたインターフェイスに追加するメソッドを含む配列です。膨大な数のメソッドがある場合は、最も人気のあるものだけをリストアップするか、リストの先頭に置くことを検討するとよいでしょう。 "WindowOrWorkerGlobalScope.fetch()" を実行すると https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch へのリンクが張られます。同じ API が所有するインターフェイスのメンバーであるメソッドを重複してリストアップしないようにしましょう。

  4. "properties" — 値は、 API に関連付けられたすべてのプロパティを含む配列です。これには API 仕様で定義されているインターフェイスのメンバーであるプロパティや、API が他のインターフェイス上で定義しているプロパティを含めることができます。膨大な数のプロパティがある場合は、最も人気のあるものだけをリストアップするか、リストの先頭に配置することを検討するとよいでしょう。 "Headers.append" を実行すると、 https://developer.mozilla.org/en-US/docs/Web/API/Headers/append へのリンクが生成されます。

  5. "events" — 値は、 API の仕様やその他の場所で定義されている API に関連するすべてのイベントを含む配列です。膨大な数のイベントがある場合は、最も人気のあるものだけをリストアップするか、リストの先頭に置くことを検討するとよいでしょう。 "animationstart" を実行すると、 https://developer.mozilla.org/en-US/docs/Web/Events/animationstart へのリンクが生成されます。

  6. "guides" — 値は、API の使用方法を説明するガイドへのリンクを定義する1つ以上のオブジェクトを含む配列です。各オブジェクトは、ガイド記事を指す部分的な URL を含む "url" と、リンクのリンクテストを定義する "title" の2つのサブメンバーを含みます。例として、次のようなオブジェクトがあります。

    { "url":   "/docs/Web/API/Detecting_device_orientation",
"title": "Detecting device orientation" }

    "Detecting device orientation" というタイトルのリンクを生成し、 https://developer.mozilla.org/en-US/docs/Web/API/Detecting_device_orientation を指します。

  7. "dictionaries" — API の一部であるすべての辞書を一覧にした文字列の配列。一般的に、特別な意味がある場合や、複数のページから参照する必要がある場合を除き、複数のプロパティやメソッドで使用される辞書のみをここにリストアップすべきです。 "RTCConfiguration" の場合は https://developer.mozilla.org/en-US/docs/Web/API/RTCConfiguration へのリンクを表示します。

  8. "types" — API で定義されている型定義子と列挙型の配列。リストを短くするために、特別に重要なものや複数のページから参照されるものだけをリストアップすることもできます。 "RTCCodecType" は https://developer.mozilla.org/en-US/docs/Web/API/RTCCodecType へのリンクを生成します。

  9. "callbacks" — 値は、その API で定義されているすべてのコールバック型のリストを含む配列です。コールバック型を含む API であっても、このグループを使用する必要はないと思われるかもしれません。文字列 "RTCSessionDescriptionCallback" を含むこの配列の項目は、 https://developer.mozilla.org/en-US/docs/Web/API/RTCSessionDescriptionCallback へのリンクが生成されます。

サイドバーで使用されるタグ

サブメンバーによっては、ページタグに基づいて子ページから自動的に発見されるものがあります。最上位 API 以下のページはサイドバーがレンダリングされるたびにクロールされ、メソッド ("Method" タグ)、プロパティ ("Property" タグ)、コンストラクター ("Constructor"タグ) の項目が自動的に生成されます。

サブメンバーにも、タグに基づいた警告アイコンが自動的に表示されます。実験的な ("Experimental" タグ)、標準外 ("Non Standard" または "Non-standard" タグ)、非推奨 ("Deprecated" タグ)、廃止 ("Obsolete" タグ) サブメンバーには装飾が追加されます。

タグベースの処理に関する詳細情報は、 APIRef ソースの中にあります。

サイドバーの挿入

GroupData.json に API の項目を追加してプルリクエストとして送信し、その変更がメインリポジトリに受け入れられたら、 {{TemplateLink("APIRef")}} マクロを使用して API リファレンスページに設置することができ、 GroupData の API に引数として使用されます。例として、 WebVR API のサイドバーは、各ページに次のように設置されています。

\{{APIRef("WebVR API")}}