APIリファレンス・仕様書HTMLを共有する方法

静的生成したAPIドキュメントの渡し方

OpenAPIの定義などから静的に生成したAPIリファレンスは、エンドポイント一覧やリクエスト・レスポンスの例、エラーコードを一つのサイトとしてまとめたものです。社内のドキュメント基盤に置けない相手に渡すときは、HTMLのまま共有するのが手軽です。

PDFに変換して送る方法もありますが、ページ内検索やリンク遷移が効きにくく、コードサンプルのコピーもしづらくなります。HTMLとして渡せば、取引先の開発者がブラウザ上でエンドポイントを探し、サンプルをそのまま手元に写せます。

仕様書はCSSやJavaScript、検索用のインデックスファイルを伴うことが多いので、関連ファイルをまとめて渡すことで生成時のレイアウトや動作をそのまま保てます。

公開前の仕様はメール認証で相手を特定する

公開前のAPI仕様には、まだ発表していない機能やパラメータの命名、内部の制限値が含まれることがあります。これが第三者に渡ると、連携の前提が崩れたり、外部に内容が漏れたりするリスクがあります。

メール認証を使えば、取引先の担当者のメールアドレスにワンタイムコードを送り、本人が入力したときだけ閲覧できるようにできます。誰が認証して見たのかを相手単位で押さえられるので、限定共有に向いています。

一時公開ページにはnoindexが付いて検索結果には出ませんが、noindexは検索除けでアクセス制御ではありません。仕様書のように内容が機微なものは、必ず認証と併用して見られる人を絞ってください。

共有前チェックリスト

APIリファレンス・仕様書HTMLを共有は、共有する中身によって確認観点が変わります。見た目、操作、個人情報、外部送信、スマホ表示のどれが重要かを先に決めてからURL化します。

チェックリスト化しておくと、毎回同じ品質で共有できます。手順が決まったら、HTML/ZIPをアップロードして共有URLを発行し、相手に確認してほしい観点と期限を添えて送ります。

• 見た目: PC/スマホ、余白、画像、フォント、折り返しを確認する
• 操作: ボタン、リンク、フォーム、遷移先を確認する
• 情報: 顧客名、社内URL、価格、未公開文言が残っていないか見る
• 共有: 認証、期限、差し替え、レビュー依頼文をセットで決める

APIリファレンスHTMLをメール認証で共有する手順

ギガサイト便なら、静的生成したリファレンスをZIPにまとめてトップページにドロップするだけで、その場で共有URLが発行されます。会員登録なしでも公開でき、認証方式や公開期限はあとから設定できます。

1. 静的生成したAPIリファレンス一式をZIPにまとめる
2. ギガサイト便のトップページにそのZIPをドロップする
3. 認証方式でメール認証を選び、取引先担当者のメールアドレスを指定する
4. 連携テストの期間に合わせて公開期限を設定する
5. 発行された〇〇.giga-site.com形式のURLを取引先に送る

仕様改訂を同じURLで届ける

API仕様は開発の途中で頻繁に変わります。エンドポイントの追加やパラメータの変更があるたびにリンクを送り直すと、取引先が古い仕様で実装を進めてしまう事故につながります。

ギガサイト便は同じURLのままファイルを差し替えられるので、改訂版を生成し直してアップロードするだけで、取引先は同じリンクから常に最新の仕様を参照できます。変更点をメールで一言添えれば、相手も追従しやすくなります。

閲覧期限とログで限定共有を締める

公開期限を設定しておけば、連携テストの期間が終わったあとに自動で閲覧できなくなり、古い仕様がいつまでも残る心配がありません。期限が切れると自動的に閲覧不可になります。

アクセスログで取引先が仕様書を開いたかを確認できるので、連携作業の進み具合の目安にもなります。本番のドキュメントサイトを立てる前段階の、確認・限定共有に向いた使い方です。