概要
私が個人開発をするときに
APIのドキュメントを書く手法については
FastAPI を使っていれば、FastAPIのSwagger UIを使って簡単にドキュメント化したりしていました。
しかし今回はPostmanを使ってドキュメントを生成できると知り、試してみたところとても簡単に公開することができたのでここでやり方を共有しようと思っています。
作り方
バックエンドの開発の時に、
Postmanで
- collection 作成
- add request からそれぞれのエンドポイントを作成
- エンドポイントにexample を作成
しておくことで、いつでもAPIが試せるようにしておくと便利なので、個人開発ではそうしています。
Postmanを利用してのデバッグ（テスト）環境整備
例えば、
authblue-api というコレクションを作成し、
- get_api_token
- delete_api_token
- get_tenants
などのリクエスト（エンドポイント）を作成、それぞれにexample を作成しているのがこちらです。
このように、それぞれのエンドポイントでexampleを用意してテストすると個人であっても、チーム開発であってもテストがしやすいのでとても便利であり、こうやっている人も多いのではないでしょうか？
ドキュメントの作成
このコレクションから、
View documentation
を選択することができます。
View Documentation をクリックすると、ドキュメント画面に移行し、
コレクションが、Exampleも含めてドキュメントの形にまとまっていることがわかると思います。
さらに、このドキュメントは右上のPublishボタンから、簡単に公開することができます。
作成したAPIドキュメント
結果として出力され、公開されたAPIドキュメンテーションは次のものになります。
開発時にPostmanを使ってデバッグしており、exampleなどをきちんと整備していれば、
ドキュメントはexample も含めて簡単に公開することができ、とても強力だと思いました。
まとめ
Postman を用いてテスト環境を整備していれば、
気の利いたドキュメントも自動で生成され、公開も非常に簡単になります。
Postmanを開発環境で使っている人はぜひドキュメントもPostmanで作ってみてはいかがでしょうか？
今回はこの辺で。
kenmaro