インポートした API のドキュメントの参照と更新

仕様書をインポートすると、Restorm はリクエストを作成するだけでなく、API のドキュメント（説明、モデル、セキュリティスキーム、例、列挙型）も保持し、インポートで作成された変数フォルダーに紐づけます。

ドキュメントを開く

変数フォルダーの ドキュメント タブ

これがメインのビューです。インポートで生成された変数フォルダーを開くと、サブタブのバーに 環境、カスタム変数、メモ と並んで ドキュメント タブがあります。

このタブはフォルダーがインポート由来である場合にのみ表示されます。手作業で作成した変数フォルダーには表示するドキュメントがありません。

その他の入口

場所	表示される内容
リクエストの ドキュメント タブ	その操作 1 つ分のドキュメント。目次や全体情報のブロックはありません。操作が仕様書内で見つかった場合にのみ表示されます
通常のフォルダーの ドキュメント タブ	そのフォルダーに含まれる操作に限定したドキュメント
変数フォルダーのホームサブタブ	ドキュメントを表示 カード — 「API のドキュメント、モデル、エンドポイントを参照します」
ウェルカム画面（API カード）	クイックリンク ドキュメント
タイトルバーの検索バー	検索結果にカーソルを合わせるとドキュメントのプレビューが表示されます

ビューの内容

上から順に、次の要素が並びます。

• API のタイトルとその説明。
• 情報ブロック：Version、Source format（ソース URL へのリンク付き）、Server（スキーム、ホスト、ベースパス）、Contact、License、Terms of service、External docs。
• タグごとのセクションと、その説明。
• 操作ごとのブロック：メソッドと URL、要約、グループのバッジ、該当する場合は deprecated バッジ、Security セクション（スキームの種類、OAuth 2 のフロー、スコープ）、そして折りたたみ可能な Example payload。
• Parameters と Responses の表（ステータスコードは色分けされます）。
• Models — スキーマのインタラクティブなグラフ。移動もズームもできます。
• Polymorphism — oneOf / anyOf / allOf による合成。
• Enums — 列挙型。フォルダー側の列挙型と統合されます。

Note

これらのセクション見出し（Models、Enums、Parameters、Responses、Security、Example payload）は、アプリケーションのどの言語設定でも英語で表示されます。画面上と照合しやすいよう、ここでもそのまま記載しています。

ドキュメントからリクエストを作成する

各操作ブロックには + Add ボタンがあり、その操作用に設定済みのリクエストを作成します。インポートが部分的にしか行われなかったときや、仕様書に新しい操作が追加されたばかりのときは、これが最短の経路です。

移動と検索

右側には目次が固定されており（Overview、Operations、Models、Enums のセクション）、折りたたみとサイズ変更ができます。モデルをクリックするとグラフまでスクロールし、該当するノードを中央に表示します。

ショートカット	動作
Ctrl+F / Cmd+F	ドキュメント内検索を開く
F3 / Enter	次の一致
Shift+F3 / Shift+Enter	前の一致
Esc	検索を閉じる

カウンターが検索結果内での位置を示します。

ドキュメントを更新する

仕様書は変化していきます。Restorm はソースを再取得し、ドキュメントとリクエストの両方に差分を適用できます。こちらの作業内容が上書きされることはありません。

URL 経由でインポートした場合のみ

再同期が利用できるのは、フォルダーが URL からインポートされた場合だけです。ファイルからのインポートや貼り付けによるインポートではソースが記録されないため、更新ボタンは表示されず、ホームサブタブには 「このフォルダはインポート可能なソースから作成されていません。」 と表示されます。

この URL は後からインターフェイス上で変更できません。ソースを変えるには、あらためてインポートしてください。

ボタンの場所

同等の入口が 2 つあります。

1. 変数フォルダーのホームサブタブにある API スペックの更新 セクション。URL、最終インポート、最終確認 が表示され、更新 ボタンがあります。
2. サイドツリーでフォルダーを右クリック → 更新。

自動チェックは行われません

Restorm はバックグラウンドで仕様書を監視しないため、新しいバージョンが公開されても通知しません。チェックは常に手動で開始します。

何が起きるか

1. 取得中は 「API スペックを更新しています…」 というウィンドウが表示されます。URL とヘッダーに含まれる {{variables}} は解決され、紐づけられた認証ルートが先に実行されます。
2. Restorm は取得したソースのフィンガープリントを、前回のインポート時に記録したものと比較します。
3. 変更がない場合 → 「API スペックは最新です。」 と表示され、そこで終了します。
4. 変更がある場合（または取得に失敗した場合）→ 再同期ウィザードが開きます。

ウィザード

• ソース URL は読み取り専用で表示されます。
• バッジから認証ルートの紐づけ・変更・解除ができ、Custom headers サブメニューから更新のたびに送信される固定ヘッダーを追加できます。
• プレビュー用のタブが 2 つあります。
  • Routes — 新しいバージョンで見つかった操作のツリー。絞り込みと選択ができます。フォルダーに既に存在する操作はロックされ、常にチェックされた状態です。選べるのは追加する新規操作だけです。
  • Documentation — 新しいバージョンのドキュメント。確定する前に読み取り専用で確認できます。
• 確定ボタンには選択した新規操作の件数が表示されます（例：Apply update (3)）。

Note

このウィザードは現時点では、アプリケーションの言語設定にかかわらず英語で表示されます（「Refresh from source」「Apply update」、タブの「Routes」と「Documentation」）。そのため、ここでも英語の表記をそのまま記載しています。

変更されるもの、変更されないもの

ここが重要な点です。仕様書は自身が記述する範囲について権威を持ち、それ以外については利用者側に決定権があります。

要素	挙動
リクエストの名前	決して変更されません
メソッドと URL	決して変更されません
既存のパラメーター、ヘッダー、パスパラメーター	値・説明・有効化の状態がそのまま保持されます
仕様書によって追加されたパラメーター	追加されます。値は仕様書の既定値、または空です
仕様書から削除されたパラメーター	リクエスト上に保持されます
新規の操作	新規インポートであれば配置されたはずの場所に追加されます（タグのフォルダーも含む）
仕様書で非推奨とされた操作	印が付き、ツリー上で淡色表示になります
仕様書から消えた操作	削除済みとして印が付き、ツリー上で取り消し線付きになります。実行は引き続き可能で、削除されることはありません
API ドキュメントと列挙型	新しいバージョンで完全に置き換えられます。これによりドキュメントタブが更新されます

ツリーから何かが削除されることは決してありません。ソースから消えた操作には印が付くだけで、消去はされません。

ソースが認証を要求する場合

レスポンスが 401 または 403 の場合、エラーメッセージ（例：HTTP 401: Unauthorized）をそのまま表示した状態でウィザードが開きます。認証ルートを紐づけるか固定ヘッダーを追加すれば、プレビューが再実行されます。

再同期できる形式

再同期に対応しているのは 12 形式です。Swagger 2.0、OpenAPI 3.x、GraphQL、gRPC、SOAP（WSDL）、OData、AsyncAPI、Postman、Insomnia、Bruno、OpenRPC、Smithy です。

それ以外の形式では、あらためてインポートすると新しいツリーが作成されます。完全な一覧はソースから更新するにあります。