Postman | The Collaboration Platform for API Development
API Request 以外にも、実は API Document を作る機能がある Postman.
比較的簡単に作れて管理も出来るので、 API Document を作る選択肢の一つにしてみてはどうでしょうか 🚀
シンプルな作り方
Documentation を選択します。
新しいコレクションを作って URL を入力します。今回は GitHub API から適当に一つだけ持ってきました。もし既に API をコレクション管理している場合は、既にあるコレクションを設定可能です。
コレクションの名前を入力します。ドキュメントの説明は設定を省略してデフォルトのままにしておきます。
こんな感じで出来上がります。 View in web を押して中身を開いてみましょう。
中身はこんな感じです。 URL だけ入力した状態だとドキュメントとして微妙なので、次は Request と Response を書いてみようと思います。
Postman に戻って作った API URL を開き、画面右上の Examples から Default を選択します。
Request と Response のサンプルを入力して保存します。
Web で開いている API Document に戻ります。いい感じに Request と Response のサンプルが設定されています。
Note
- 認証情報などもまとめてドキュメント管理できる。
- コレクション管理しておけば API Request のテストをするときも簡単に出来る。
- Swagger や API Blueprint に比べて GUI から書きやすい。
- 環境設定を複数持てるので Develop / Staging / Production などを分けることが出来る。
- 制約はあるけど Web 上で簡単に公開できる。 *逆に言うと簡単すぎるのでセキュリティには気をつけてください。
- コレクションを json でエクスポートできるので Git 管理も可能。
- 使ったことはないけど Mock Server としても使えるらしい。
- スクリプトも書けるらしい。
リンク
40 秒の動画説明があるトップページ: Postman | API Documentation Generator
Postman Document: Documenting your API | Postman Learning Center