POSTMANでAPIドキュメント作成時に便利な機能紹介

この記事は eureka Advent Calendar 2018 3日目の記事です。

はじめに

エウレカで今年新卒入社した

Ryosuke Sugihara

です。現在はAPI Teamに所属しています。好きな食べ物は🍣と🍜、趣味はTwitterとサバゲーです。

これまでPairsの開発を進めていく上でAPIドキュメントの整備に関して課題に挙がる事が度々あり、今回この課題を解決するためPOSTMANを導入しました。

この記事ではAPIドキュメントをPOSTMANで作成する際にどのように作っていくのか、またどのようにしたら更新の手間が省けるのかの観点で使ってみて便利だなと感じた3つの機能について紹介します。

POSTMANとは？

POSTMANはRestAPIを簡単に叩けたり、一度叩いた結果を保存しておきドキュメントとしてまとめることもできるツールです。

POSTMANの便利な機能

APIドキュメントを作る際に便利な以下の3つの機能を紹介します。

1. Import
2. Collections
3. Example

1. Import

Importの機能はcurlからリクエストを追加することができChromeの開発者ツールを使うと楽にPOSTMAN上でリクエストを作成することができます。

追加方法は、POSTMANの左上部のImportを押します。

import

Importを押すと以下の画面が開きます。

import

ここで試しに https://medium.com/ を開いたときに叩かれhttps://medium.com/_/api/home-feedをchromeのChromeの開発者ツールからCopy as cURLでコピーしてきましょう。

コピーできたらPaste Raw Textに貼り付けてImportを押しましょう。

そうすると以下のようにHeader情報やパラメーター情報が入力された状態になります。この機能と後述するExampleを組み合わせるとAPIドキュメントを作成する際に強力な手助けとなります。

2. Collections

Collectionsはリクエストを集約し、管理する機能です。Collectionsを追加する時は左上部のNewから作成することができます。POSTMANにはサンプルとしてPostman EchoというCollectionsがあります。フォルダによって用途別にリクエストが分けられ管理されています。

Importでcurlから取り込んだリクエストをCollectionsに追加していき、 DescriptionというMarkdownで記述可能な赤枠の部分にリクエストのパラメータやHeader、レスポンスのキー・型、Exampleの説明を記述することでAPIドキュメント化していこうと考えています。

3. Example

Exampleは一度叩いたリクエストの情報とレスポンスを保存しておくことができ、再度APIを叩かずとも確認できる機能です。Web上のAPIドキュメントでは赤枠の部分がExampleで青枠がExampleの名前、緑枠がステータスコードです。

Exampleは一つのリクエストに対して複数保存することができ、パラメータやユーザの状態によってレスポンスのパターンが変化する際にそれらを網羅するのに有効です。

まとめ

今回紹介したImport、Collections、Exampleをうまく使うことで頻繁に更新されるAPIの仕様を簡単にアップデートできるようになると考えています。他にも今回紹介しなかったProxyを使用したリクエストのキャプチャやテストを簡単に記述できたりと色々な便利な機能があります。

サービスの成長が早い場合、APIドキュメントは作っただけではすぐにそれは使えなくなってしまいます。作成のしやすさと更新のしやすさを観点に入れる必要があるのです。