Brunoを導入されている方なら、その魅力はすでにご存知でしょう。コレクションはプレーンな.bruファイルとしてGitリポジトリに保存され、コードとともにバージョン管理され、クラウドアカウントは不要です。これは、データを所有したがるAPIクライアントに対する、クリーンでオフラインファーストな解決策です。
しかし、遅かれ早かれ、Brunoではうまく答えられない質問に出くわします。「ドキュメントはどこにありますか？リンクを送ってもらえますか？」ここでチームは壁にぶつかります。Brunoはリクエストを送信するために作られており、共有可能なドキュメントポータルを公開するためではありません。このガイドでは、BrunoのAPIドキュメント生成について正直に、Brunoが提供するもの、提供しないもの、そして消費者に手渡すための実際のURLが必要な場合に、スペックからドキュメントを生成してホストする方法を説明します。
ボタン
チームがAPIドキュメントに実際に必要とするもの
どんなツールを評価する前にも、目標を明確にすることが役立ちます。「APIドキュメント」と言うとき、通常は連携して機能する3つのことを意味します。
- 共有可能なURL。フロントエンド開発者、パートナー、QAは、リポジトリをクローンしたりクライアントをインストールしたりすることなくドキュメントを読む必要があります。Slackのリンクはただ機能するべきです。
- 同期が保たれたドキュメント。実際のAPIから乖離したドキュメントは、ないよりも悪いものです。なぜなら、人々を自信を持って間違った方向に導くからです。ドキュメントはスペックを追跡する必要があります。
- インタラクティブな「試す」体験。エンドポイントの説明を読むのも良いですが、認証やサンプルペイロードが入力されたドキュメント化されたエンドポイントに対して実際のリクエストを送信することが、ドキュメントを使用可能なリファレンスに変えます。
この3つすべてを達成すれば、ドキュメントは唯一の信頼できる情報源になります。どれか一つでも欠けると、人々は直接あなたに質問することに戻り、それはスケールしません。
Brunoのドキュメントの現状
Brunoに対して公平に評価しましょう。なぜなら、いくつかの点で優れているからです。
Brunoのコレクションは人間が読めます。.bru形式はプレーンテキストなので、リポジトリを閲覧するエンジニアはリクエストファイルを開いて、メソッド、URL、ヘッダー、ボディを確認できます。Brunoは、リクエストごとにdocsブロックとアプリ内のMarkdownドキュメントビューもサポートしているため、エンドポイントが何をするかを説明する文章を添付できます。すべてがGitにあるため、それらのメモは他の変更と同様にプルリクエストでレビューされます。コードベースで作業する内部チームにとっては、これは正当なドキュメントの形式です。
正直なギャップは公開です。Brunoには、組み込みの、ホストされた、自動生成された公開ドキュメントポータルがありません。コレクションをカスタムドメインを持つ安定したURLのウェブサイトに変換する「公開」ボタンはありません。アプリ内ドキュメントビューは、すでにBrunoをインストールし、コレクションをクローンしている人々に表示されますが、これはまさにドキュメントを最も必要としない層です。
そのため、チームは工夫します。一般的な回避策としては、コレクションやOpenAPIファイルをエクスポートし、それを別の静的ドキュメントジェネレーターに投入したり、CIでドキュメントサイトを構築したり、誰かが記憶で更新する手書きのREADMEを維持したりすることが挙げられます。これらは機能しますが、維持すべきビルドパイプラインと、情報が乖離する可能性のある別の場所を追加します。ドキュメントは、テストに使用するツールの第一級の出力ではなく、サイドプロジェクトになってしまいます。
Docs-as-codeの原則
これについて考えるよりクリーンな方法は、Brunoユーザーがすでに半分信じていることです。ドキュメントを、分離された成果物ではなく、仕様の生成物として扱うことです。
docs-as-codeワークフローでは、APIは通常OpenAPIという機械可読な仕様で一度記述されます。その仕様はGitに存在し、プルリクエストでレビューされ、契約として機能します。ドキュメント、モックサーバー、クライアントSDKはすべてそこから*生成されます*。契約が変更されると、変更は一箇所でレビューされ、下流のすべてがそれに従います。
この利点は、「ドキュメントを更新する」という忘れがちなタスクがなくなることです。ドキュメントは仕様のレンダリングです。仕様が正しくレビューされていれば、ドキュメントも正しいということです。これは、BrunoがコレクションをGitに保持することで示唆している原則ですが、公開の段階には至っていません。
代わりに、スペックからドキュメントを生成してホストする
これがApidogが埋めるために作られたギャップです。Apidogは、スペック中心のGitフレンドリーなメンタルモデルを維持しつつ、Brunoが省いた部分、つまり、別のビルドパイプラインを必要とせずに、インタラクティブでホストされたドキュメントサイトをスペックから直接生成する機能を追加しています。
ApidogにOpenAPIスペックを指示するだけで、ドキュメントポータルが自動的に生成されます。その結果は以下の通りです。
- 共有可能なURLでホストされ、リンクを持つ人なら誰でも何もインストールせずにドキュメントを読むことができます。
- カスタムドメインにマウント可能で、
docs.yourcompany.comのようなアドレスでドキュメントを公開し、ブランドに合わせることができます。 - インタラクティブで、ドキュメント化されたパラメータ、ヘッダー、認証を使用して実際のリクエストを送信する組み込みの「試す」パネルを備えています。
- スペックから生成されるため、手書きで乖離する可能性のあるコピーではなく、APIが実際に宣言している内容をドキュメントが反映します。
同じスペックがApidogのテストやモックも駆動するため、一つのAPIについて3つの説明を維持する必要はありません。一度記述すれば、それを再利用できます。
ウォークスルー：スペックから共有可能なURLへ
OpenAPIスペックからドキュメントを公開する簡単な手順は以下の通りです。
| ステップ | アクション | 結果 |
|---|---|---|
| 1 | ApidogでOpenAPIスペックをインポートまたは作成する | エンドポイント、スキーマ、例が自動的に入力される |
| 2 | プロジェクトのドキュメント設定を開く | ドキュメントがスペックから生成され、設定準備完了 |
| 3 | 可視性と（オプションで）カスタムドメインを選択する | ドキュメントは公開、プライベート、またはパスワード保護される |
| 4 | 公開する | ライブのホスト型ドキュメントサイトが安定したURLで作成される |
| 5 | リンクを共有する | 消費者がドキュメントを読み、「試す」リクエストを実行する |
すでにBrunoコレクションをお持ちの場合は、まずOpenAPIに変換し、そのスペックをインポートできます。そこから公開手順は同じです。重要なのは、ドキュメントの生成とホスティングが、自分で組み立てるパイプラインではなく、提供される機能であるということです。
スペック変更時にドキュメントの同期を保つ
ドキュメントのURLは、正確であり続ける場合にのみ有用です。場当たり的な設定での失敗パターンは、誰かがエンドポイントの変更をリリースし、ドキュメントを忘れてしまうことです。
ドキュメントがスペックから生成される場合、そのリスクは小さくなります。スペックを編集し、スペックの変更は他のコード変更と同様にレビューされ、公開されたドキュメントは新しい状態を反映します。覚えておくべき並行するドキュメントはありません。レスポンススキーマにフィールドを追加すればドキュメントに表示され、エンドポイントを非推奨にすればドキュメントにその旨が記されます。契約を正しく保つためにすでに行っている作業が、ドキュメントを正しく保つ作業と同じになるのです。
これこそが、docs-as-code原則の実用的なメリットです。正確性は、どうせやりたいワークフローの副産物となり、規律に依存する別の雑用ではなくなります。
よくある質問
Brunoは公開APIドキュメントを生成し、ホストできますか？
Brunoは、読み取り可能な.bruコレクションファイルと、Gitでレビューされるアプリ内Markdownドキュメントビューを提供します。共有可能なURLを持つ、組み込みの、ホストされた、自動生成された公開ドキュメントポータルは含まれていません。Brunoから公開ドキュメントを公開するには、通常、チームはスペックをエクスポートし、別の静的ドキュメントジェネレーターを実行しますが、これにより維持すべきパイプラインが増えます。
APIから共有可能なドキュメントURLを取得するにはどうすればよいですか？
OpenAPIスペックでAPIを記述し、それからホストされたドキュメントを生成するツールを使用します。Apidogでは、スペックをインポートし、可視性を設定し、オプションでカスタムドメインをアタッチして公開します。出力は、安定したURLを持つライブドキュメントサイトで、インタラクティブな「試す」パネルがあり、直接共有できます。
ドキュメントを公開するためにBrunoコレクションを放棄する必要がありますか？
いいえ。既存のBrunoコレクションをOpenAPIに変換し、そのスペックをドキュメントツールにインポートできます。エンドポイント、スキーマ、例は引き継がれ、スペックはバージョン管理下に置かれます。移行はスペックレイヤーで行われるため、Brunoで培ったdocs-as-codeの習慣は引き続き適用されます。
ボタン