Brunoを使っているチームなら、.bruファイルをGitで管理できるメリットはすでに理解しているはずです。コレクションはプレーンテキストとしてリポジトリに保存でき、APIリクエストをコードと同じようにレビューできます。クラウドアカウントに依存せず、オフラインファーストでAPIクライアントを運用できる点は、Brunoの大きな強みです。
一方で、APIをチーム外の開発者、QA、パートナーに共有する段階になると、別の課題が出てきます。
「APIドキュメントのURLを送ってください」
Brunoはリクエストを作成・実行するためのツールであり、共有可能な公開ドキュメントポータルを生成・ホストするためのツールではありません。
この記事では、Brunoでできること・できないことを整理し、OpenAPIスペックから共有可能なAPIドキュメントURLを作成する実装手順を紹介します。
チームがAPIドキュメントに実際に必要とするもの
APIドキュメントに必要なのは、単なる説明文ではありません。実務では、次の3つが揃っている必要があります。
-
共有可能なURL
- フロントエンド開発者、QA、外部パートナーが、リポジトリをcloneしたりAPIクライアントをインストールしたりせずに読めること
- SlackやIssueに貼ったリンクがそのまま使えること
-
API仕様と同期された内容
- 実装とドキュメントがズレると、利用者は誤った情報を信じて実装してしまいます
- ドキュメントは手書きの別管理ではなく、APIスペックから生成されるべきです
-
インタラクティブな「試す」機能
- エンドポイントの説明だけでなく、パラメータ、ヘッダー、認証、サンプルボディを使って実際にリクエストできること
- 利用者がドキュメント上で挙動を確認できると、問い合わせが減ります
この3つが揃うと、APIドキュメントはチームの「信頼できる参照先」になります。
Brunoのドキュメント機能でできること
Brunoには、内部チーム向けのドキュメントとして有用な機能があります。
.bruファイルはプレーンテキストなので、GitHubなどで直接確認できます。たとえば、リクエストファイルを開けば、HTTPメソッド、URL、ヘッダー、ボディを確認できます。
Brunoでは、リクエストごとにdocsブロックやMarkdown形式の説明を追加できます。
meta {
name: Get user
type: http
seq: 1
}
get {
url: {{baseUrl}}/users/{{userId}}
body: none
auth: bearer
}
docs {
# Get user
指定したユーザーIDに対応するユーザー情報を取得します。
}
このようなファイルをGitで管理すれば、APIリクエストと説明を同じプルリクエストでレビューできます。
内部開発チームがBrunoをインストールしていて、同じリポジトリを扱う場合は、この運用でも十分に機能します。
Brunoで難しいこと
Brunoの制約は、公開ドキュメントの生成とホスティングです。
Brunoには、次のような機能は標準ではありません。
- コレクションから公開APIドキュメントサイトを自動生成する
- 生成したドキュメントを安定したURLでホストする
-
docs.example.comのようなカスタムドメインで公開する - API利用者がブラウザ上でリクエストを試せる公開ポータルを提供する
つまり、Brunoのドキュメントは基本的に「Brunoを使っていて、リポジトリにアクセスできる人」向けです。
外部の開発者や非Brunoユーザーに対してAPI仕様を共有するには、別の仕組みが必要になります。
よくある回避策
Brunoだけで公開ドキュメントを完結できない場合、チームは次のような方法を取ることが多いです。
- BrunoコレクションをOpenAPIに変換する
- OpenAPIファイルを静的ドキュメントジェネレーターに渡す
- CIでHTMLをビルドする
- GitHub Pages、Netlify、Vercelなどでホストする
- API変更時に再生成する
この方法は実現可能ですが、次の問題があります。
- ドキュメント生成用のCI/CDを保守する必要がある
- OpenAPIファイルとBrunoコレクションの同期が必要になる
- ドキュメント更新が別タスクになり、忘れられやすい
- 「リクエストを試す」機能を追加するには、さらに設定が必要になる
結果として、APIドキュメントがサイドプロジェクト化しやすくなります。
Docs-as-codeの考え方
この問題を避けるには、APIドキュメントを手書きの成果物ではなく、APIスペックから生成される成果物として扱うのが効果的です。
docs-as-codeワークフローでは、API仕様をOpenAPIなどの機械可読な形式で管理します。
基本的な流れは次の通りです。
OpenAPI Spec
├── API Documentation
├── Mock Server
├── API Tests
└── Client SDK
OpenAPIスペックをGitで管理すれば、APIの契約をプルリクエストでレビューできます。
openapi: 3.0.3
info:
title: User API
version: 1.0.0
paths:
/users/{userId}:
get:
summary: Get user
parameters:
- name: userId
in: path
required: true
schema:
type: string
responses:
"200":
description: User found
このスペックからドキュメントを生成すれば、ドキュメントの更新は「別タスク」ではなくなります。
API仕様を更新すると、ドキュメントもその仕様に従って更新されます。
Apidogでスペックからドキュメントを生成・ホストする
Apidogは、OpenAPIスペックをもとにAPIドキュメントを生成し、ホストできるAPIプラットフォームです。
Brunoのようにスペック中心のワークフローを維持しながら、次のような公開ドキュメント機能を追加できます。
ApidogでOpenAPIスペックを読み込むと、ドキュメントポータルを生成できます。
生成されたドキュメントでは、次のことができます。
- 共有可能なURLでAPIドキュメントを公開する
- ブラウザだけで閲覧できるため、利用者はツールをインストールしなくてよい
- カスタムドメインで公開できる
- ドキュメント上でリクエストを試せる
- パラメータ、ヘッダー、認証、リクエストボディをスペックから表示できる
- OpenAPIスペックに基づいて内容を維持できる
同じスペックをテストやモックにも利用できるため、API仕様、ドキュメント、検証用データを別々に管理する必要が減ります。
ウォークスルー：OpenAPIスペックから共有URLを作る
OpenAPIスペックから共有可能なAPIドキュメントURLを作成する流れは次の通りです。
| ステップ | アクション | 結果 |
|---|---|---|
| 1 | ApidogでOpenAPIスペックをインポートまたは作成する | エンドポイント、スキーマ、サンプルが読み込まれる |
| 2 | プロジェクトのドキュメント設定を開く | スペックに基づいたドキュメントが生成される |
| 3 | 公開範囲を設定する | 公開、非公開、パスワード保護などを選択できる |
| 4 | 必要に応じてカスタムドメインを設定する |
docs.example.comのようなURLで公開できる |
| 5 | 公開する | ホストされたAPIドキュメントURLが作成される |
| 6 | URLを共有する | 利用者がブラウザで閲覧し、リクエストを試せる |
すでにBrunoコレクションを使っている場合は、まずOpenAPIスペックに変換し、そのスペックをApidogにインポートします。
Bruno Collection
↓
OpenAPI Spec
↓
Apidog
↓
Hosted API Documentation
重要なのは、ドキュメント生成とホスティングを自前のCIパイプラインとして組み立てるのではなく、スペックから直接公開できる状態にすることです。
スペック変更時にドキュメントの同期を保つ
APIドキュメントのURLは、内容が正確でなければ意味がありません。
よくある失敗パターンは次のようなものです。
- バックエンドでレスポンススキーマを変更する
- APIはリリースされる
- ドキュメント更新を忘れる
- フロントエンドや外部開発者が古い仕様を見て実装する
スペックからドキュメントを生成していれば、このリスクを下げられます。
たとえば、レスポンスにavatarUrlを追加する場合、OpenAPIスペックを更新します。
components:
schemas:
User:
type: object
properties:
id:
type: string
name:
type: string
avatarUrl:
type: string
format: uri
この変更がレビューされ、公開ドキュメントに反映されれば、利用者は最新のレスポンス構造を確認できます。
エンドポイントを非推奨にする場合も同様です。
paths:
/legacy-users:
get:
summary: Get legacy users
deprecated: true
responses:
"200":
description: Legacy user list
スペックを正しく保つ作業が、そのままドキュメントを正しく保つ作業になります。
Brunoを使い続けながら公開ドキュメントを作る構成例
Brunoを完全に捨てる必要はありません。
内部のAPI実行や検証にBrunoを使いながら、公開ドキュメントはOpenAPIスペックから生成する構成も可能です。
Repository
├── bruno/
│ ├── users/
│ └── auth/
├── openapi.yaml
└── README.md
運用例は次のようになります。
- 開発者はBrunoでAPIリクエストを作成・確認する
- API契約は
openapi.yamlに反映する -
openapi.yamlをレビューする - Apidogにスペックをインポートする
- 公開ドキュメントURLを共有する
この構成なら、BrunoのGitベースの運用を維持しながら、外部共有用のドキュメントURLも提供できます。
よくある質問
Brunoは公開APIドキュメントを生成し、ホストできますか？
Brunoは、読み取り可能な.bruファイルとアプリ内のMarkdownドキュメントビューを提供します。
ただし、共有可能なURLを持つ、ホストされた公開APIドキュメントポータルを標準機能として生成するものではありません。
公開ドキュメントを作るには、通常はOpenAPIスペックへ変換し、別のドキュメント生成・ホスティング手段を使う必要があります。
APIから共有可能なドキュメントURLを取得するにはどうすればよいですか？
OpenAPIスペックでAPIを定義し、そのスペックからホストされたドキュメントを生成するツールを使います。
Apidogでは、OpenAPIスペックをインポートし、公開範囲やカスタムドメインを設定して公開できます。
公開後は、安定したURLをチームや外部利用者に共有できます。
ドキュメントを公開するためにBrunoコレクションを放棄する必要がありますか？
いいえ。
Brunoコレクションを使い続けながら、OpenAPIスペックをドキュメント生成の元データとして利用できます。
既存のBrunoコレクションをOpenAPIに変換し、そのスペックをApidogにインポートすれば、エンドポイント、スキーマ、サンプルをもとに公開ドキュメントを作成できます。
Brunoで培ったGitベースの運用を維持しつつ、API利用者向けには共有可能なドキュメントURLを提供できます。
Top comments (0)