PostmanでAPIドキュメント（Document）を作成する

PostmanはAPIテスト用の定番ソフトとして、多くのAPI開発者に利用されています。テストの他、Postmanは、APIドキュメントの作成をもサポートできます。本文では、Postmanを使って、APIドキュメントを作成する方法を皆さんに紹介します。PostmanでAPIを設計してAPIドキュメントが必要となる場合は、ぜひ本文の内容を参照してください。

Apidogで生成したドキュメントのサンプル：

PostmanのAPIドキュメントについて

PostmanのAPIドキュメント機能は、APIの仕様や使い方を記述・公開できる便利な機能です。主に次のことを実現しています。

初心者向け：Postmanの基本的な使い方を

Postmanは、APIテストなどを行うための定番のツールになります。API戦略を実施する場合は、Postmanを利用することで、その効率性を大幅に向上できます。そこで、本文では、基本的なPostmanの使い方を皆さんに紹介して、Postmanを全く使ったことがないユーザーでも、本文の内容を参照して、Postmanを使いこなすことができると思います。

Apidogブログ - Apiに関する先端知識を取得するshimizu chioka

• リクエストからAPIドキュメントを生成
• YAMLからAPI仕様を記述してAPIドキュメントを生成

Postmanでリクエストを追加して送信すると、そのリクエストのAPIのエンドポイント、パラメータ、レスポンスの構造などを自動的にドキュメント化できます。それに、APIドキュメントでマークダウン形式にも対応できるので、マークダウン形式で説明文や例を追加することも可能です。そして、APIドキュメントを作成した後、他人に共有したい場合は、そのドキュメントをウェブ上で公開することもできます。

また、Postmanは、OpenAPI仕様であるOpenAPI Specificationに対応できるので、APIを０から設計する場合は、YAMLやJSONを手動で記述する必要があり、API設計用のGUIを提供してくれないのが惜しいです。

ご案内：APIのリクエストを保存してドキュメント化するには、PostmanでまずCollectionを作成する必要があります。そして、リクエストの送信結果は自動的にドキュメントに反映されます。

PostmanでAPIドキュメントを作成する方法

それでは、PostmanでAPIドキュメントを作成するには、どうしたらいいですか？次は、PostmanでAPIリクエストを保存してAPIドキュメントを生成する方法と、PostmanでYAMLやJSONでAPI仕様を設計する方法を皆さんに紹介したいと思います。

リクエストからAPIドキュメントを生成

Postmanでリクエストを保存するには、まずはコレクションを作成する必要があります。そこで、まずはコレクションを作成して、そこにリクエストを作成する必要があります。

ステップ⒈Postmanを開くと、左上の「新規」ボタンをクリックして、リクエストを作成します。そして、リクエストの画面で、HTTPメソッド、エンドポイント及びその他の情報を記入した上、「保存」ボタンをクリックします。

ステップ⒉左側のメニューからこのリクエストを右クリックして、「ドキュメントを見る」を選択します。

ステップ⒊ここでこのリクエストのAPIドキュメントが表示されます。必要に応じて、「公開」ボタンをクリックして、ドキュメントを公開することも可能です。

YAML/ JSONからAPI仕様を記述してAPIドキュメントを生成

PostmanでリクエストからAPIドキュメントを生成する他、APIを設計する必要がある場合、YAML /JSONファイルを記述するか、インポートすることで、API仕様に基づいて、APIドキュメントを生成することも可能です。

ステップ⒈Postmanを開くと、左側の「API」を選択して、「＋」ボタンをクリックすることで、新しいAPIを作成します。そして、「Import」で既存のYAML/ JSONファイルからインポートすることもできますし、「create」をクリックして新しいYAML/ JSONファイルを作成して、手動で記述することもできます。

ステップ⒉「Create」をクリックして、どのフォーマットでAPI仕様を記述するかを選択して、「Create Definition」を選択します。

ステップ⒊ここで選択したフォーマットでAPI仕様を手動で記述します。

ステップ⒋記述が終わると、APIの仕様に基づいてAPIのドキュメントが自動的に生成されます。

ご案内：０からAPI仕様を設計する場合、PostmanはGUIを提供することがなく、手動でYAMLやJSONなどの定義ファイルを記述する必要があります。

ApidogでAPIを直感に設計、より綺麗なドキュメントを生成

Postmanとは別に、Apidogというツールは、APIをより直感的に設計できます。ApidogはAPI設計用のGUIを提供しているので、全くYAMLやJSONを手動で記述する必要がありません。APIの設計が終わると、そのAPI仕様書を生成して、他人に共有したり、インタネットで公開したりすることも可能です。

Apidogは、非常に直感的なGUIでAPIを簡単に設計することができます。Apidogを使用すると、HTTPメソッド、エンドポイント、APIの詳細情報、ステータスコード、ユースケースなどを簡単な操作で追加することができます。手動でYAMLやJSONコードを打つ必要がなくなります。

また、APIを定義すると、Apidogの共有機能を使って、非常にわかりやすいAPI仕様書を生成したり、他人に共有したりする事ができます。

左側メニューから「共有」をクリックして、「新しい共有」を選択すると、次のような共有設定が表示されます。ここで、共有するAPIを選択して、必要に応じてセキュリティ設定や言語の設定を終えて、「保存」をクリックします。

ここで、「開く」をクリックすると、本文の最小にシェアした綺麗なドキュメントを確認することができるようになります。

まとめ

PostmanはAPIのテスト実行とドキュメント化に大変便利なツールですが、大規模なAPI設計には向いていない面があります。具体的には、YAMLやJSON形式で全てのAPI定義を手作業で記述する必要があるため、生産性に課題があります。また、生成されるドキュメントの見た目や体裁についても、多くの場合手直しが必要です。

こうしたPostmanの課題を解決するのが、Apidogというツールです。

ApidogはGUIベースのAPIデザインツールで、直接エンドポイントやパラメータ、レスポンス構造などのAPI定義をインタラクティブに設計できます。コード記述の手間が不要で、直感的な操作性が大きな特徴です。設計されたAPIは綺麗なドキュメントとしてそのまま出力可能です。マークダウンによる解説書きやコメント追加も簡単に行えるので、手軽なAPIドキュメント作成に最適です。