メニュー

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

how create api documentation postman

問題を排除するために楽器を試してください

このチュートリアルでは、Postman Toolが提供するAPIドキュメントサポートを使用して、最小限の労力で見栄えの良いスタイルのドキュメントを作成する方法について説明します。

内部向けであろうと公開向けであろうと、どのAPIにとっても、ドキュメントはその成功にとって最も重要な要素の1つです。

その主な理由は、ドキュメントはユーザーとのコミュニケーション方法です。

  • APIはどのように使用する必要がありますか？
  • サポートされているすべてのステータスコードは何ですか？
  • エラーコードは何ですか？
  • どのすべてのメソッドタイプが公開されていますか？

このすべての情報は、必要に応じてAPIを使用または実装するために必要です。

=> ここで簡単な郵便配達員トレーニングシリーズに気をつけてください。

Postman-APIドキュメントの作成

何でjarファイルを開くか

Postmanは、使いやすいドキュメント手法を提供します。基本的なドキュメントについては、Postmanコレクションのボタンをクリックするだけで、APIドキュメントのパブリックURLを取得できます。

学習内容：

PostmanでのAPIドキュメントの作成

ドキュメント機能

Postmanドキュメントジェネレータの主な機能は次のとおりです。

  • マークダウン構文をサポートしています。マークダウンは一般的なドキュメント構文であり、Githubプロジェクトで通常気付くはずです。これにより、スタイリングとテキストの書式設定をより身近で簡単にすることができます。
  • ドキュメントを作成するための特定の構文/要件はありません。リクエストとコレクションの情報は、ドキュメントを生成するための最良の方法で利用されます。
  • パブリックURLまたはカスタムドメイン（エンタープライズユーザーの場合）に公開できます。
  • C＃、PHP、Ruby、Python、Nodeなどのさまざまな言語でAPIを呼び出すためのコードスニペットを生成します。

ドキュメントの作成

Postmanドキュメントジェネレーターは、コレクション、フォルダー、および個々のリクエストの説明を参照し、コレクションのドキュメントを作成または生成するときにそれらを照合します。

ヘッダー、クエリ文字列パラメーター、フォームパラメーターなどのさまざまなリクエストパラメーターを利用し、リクエストドキュメントでこれらの値の使用を示します。

これがビデオチュートリアルです：

他の記事と同じテストAPIを使用して、3つのリクエストで基本的なコレクションを作成しましょう。コレクションの説明と個々のリクエストにいくつかの情報を追加し、リクエストとレスポンスの例をいくつか作成します。これらもドキュメントの作成中にキャプチャされます。

以下の手順に従って、リクエストに関する基本情報を追加し、ドキュメントを作成します。

＃1） ユーザーの登録、ユーザーのログイン、ユーザーの取得の3つのリクエストでコレクションを作成します（参照 ここに リクエストペイロードとAPIURLの場合）。

＃二） それでは、マークダウン形式の情報をコレクションに追加しましょう。マークダウンは、Githubのほぼすべてのドキュメントで使用されている標準形式です（マークダウンの詳細については、 ここに ）。

以下のように、コレクションの説明にマークダウン形式でいくつかの情報を追加します。

マークダウン形式のコレクションの説明

マークダウンがどのように見えるかをプレビューするには、オープンソースのWebポータルを参照してください ここに。

マークダウンドキュメント

＃3） 次に、コレクション内の個々のリクエストに説明を追加します。コレクションと同様に、マークダウン形式はリクエストの説明でもサポートされています（マークダウンガイドの詳細については、を参照してください）。 ここに ）。

ユーザー登録エンドポイントのリクエストの1つのサンプルを見てみましょう（同じことが他のリクエストにも適用できます）。

マークダウンテキスト：

API endpoint to *Register* a user in the system. > A successful registration will result in a *HTTP 200* Status code

マークダウンプレビュー：

マークダウンプレビュー

＃4） すべてのAPIエンドポイントについて、ドキュメントジェネレーターで使用される例をキャプチャまたは保存しましょう。

例は、考慮に入れるAPIリクエストのサンプルリクエスト/レスポンスに他なりません。応答を例として保存すると、ドキュメントジェネレータはそれをドキュメント自体の一部としてキャプチャできます。

例を保存するには、 「送信」 ボタンをクリックしてリクエストを実行し、(レスポンス)タブで( 応答の保存->例として保存 。

例を保存

サンプルが保存されると、コレクションに永続化され、将来いつでもアクセスできます。 例 リクエストビルダーのリンク。

＃5） 上記の情報をすべて追加したら、ドキュメントのプレビューを作成する方法を見てみましょう。

コレクションオプションを開き、「 ドキュメントを公開する 」。

ドキュメントを公開する

注意： ここで注意すべき重要な点は、Postmanに登録されているユーザーのみがPostmanのドキュメントの公開機能を使用できることです。登録は無料ですが、メールアカウントから行う必要があります。コレクションやワークスペースの共有、モニターの作成など、登録済みのアカウントに追加される他の機能/機能があります。

＃6） 一度「 ドキュメントを公開する 」が実行されると、ブラウザタブが開き、Postmanコレクションの詳細が表示されます（内部的に、Postmanは、ユーザーのローカルファイルシステムに加えて、このコレクションを独自のサーバーにホストします）。

ドキュメントコレクション

クリック 「プレビュー」 公開される前にドキュメントを表示します。

「」 コレクションを公開する 」リンクは、一般にアクセス可能なURLにドキュメントを公開します。一般に、公開URLに公開するために機密性の高い認証情報を持つAPIを公開することはお勧めしません。このようなAPIは、Postmanのエンタープライズアカウントを持つカスタムドメインを使用して公開できます。

＃ 7） ドキュメントのプレビューがどのように見えるか見てみましょう。 「 ドキュメントのプレビュー 」は、Postmanのサーバーでホストされているプレビューモードでドキュメントを開きます。ドキュメントにどのような詳細が記録されているかを見てみましょう（さまざまな場所で構成したため）。 例えば 、コレクションの説明、リクエストの説明と例）。

Postmanドキュメントサンプル

Markdownでのリクエストの説明

上記の2つのスクリーンショットでは、コレクションとリクエストの説明に追加されたすべての情報が、ドキュメントプレビューでマークダウンスタイルの方法でキャプチャされていることがわかります。

単体テストと統合テストの例

また、ドキュメントにはデフォルトで強調表示されている言語バインディングが記載されているため、リストされている言語でAPIリクエストを直接作成したい人にとっては非常に簡単です。

＃8） また、背景色の変更、ヘッダーテンプレートの背景と前景色の変更など、非常に基本的なスタイルの変更を実行することもできます。ただし、全体として、デフォルトのビュー自体で、多くのドキュメントをキャプチャする非常に優れたドキュメントのセットを公開できます。 APIに関する重要な詳細。

結論

このチュートリアルでは、Postmanが提供するAPIドキュメントのサポートについて説明しました。これを使用すると、最小限の労力で見栄えの良いスタイルのドキュメントを作成できます。

また、生成されたドキュメントに適用できる多くの優れたテンプレートとユーザー定義のスタイル設定が可能になり、ドキュメントをパブリックURLに公開することもできます。

プライベートAPIエンドポイントの場合、エンタープライズアカウントまたはユーザー用に構成できるカスタムドメインにドキュメントを公開するためのプロビジョニングもあります。

さらに読む= >> PactBrokerにPact契約を公開する方法

=> Postmanを最初から学ぶには、こちらにアクセスしてください。

推奨読書

^