Go to Qiita Advent Calendar 2024 Top
LoginSignup
7
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@yokawasa(Yoichi Kawasaki)inPostman

OpenAPIを元にしたPostmanコレクションの作成・更新を自動化する方法

Last updated at Posted at 2024-05-13

はじめに

これは、REST APIの仕様書としてOpenAPI Specification（以下、OAS）を管理していて、そのOASを元にPostmanコレクションを作成・更新したい思っている人向けの記事です。

PostmanはGUIベースのアプリケーションであり、このGUIからOASをインポートして新規のコレクションを作成できます。作成後は、GUIを介してコレクションを直接更新ができます。しかし、この手動でのGUIを通したコレクションの作成・更新だけでなく、自動化したいニーズもあるかと思います。たとえば、GitHubなどのコード管理システムでOASファイルを管理しているシナリオでは、以下のような手順でのコレクションの作成・更新が考えられます：

  1. コード管理システム（GitHubなど）で管理しているOASファイルを更新する
  2. OASファイルの更新をトリガーにCI/CDワークフロー（GitHub Actionsなど）が実行され、その中でOASを元にコレクションを自動的に作成・更新する

本記事では、このようなシナリオを実現するために、Postmanが提供するOSSライブラリであるopenapi-to-postmanと、Postmanクラウド上のPostmanアセットを管理・操作できるPostman APIを活用する方法を紹介します。

openapi-to-postmanとは？

Postmanが提供するOSSで、OpenAPI 3.0 仕様を Postman コレクションv2 形式に変換するためのCLIやライブラリを提供します。

以下、openapi-to-postmanを活用してOASファイル oas.yamlからPostmanコレクションデータファイルを生成する例です。

CLIで実行する例:

# Postmanコレクションデータファイル、collection.jsonを出力
openapi2postmanv2 -s oas.yaml -o collection.json -p -O folderStrategy=Tags,includeAuthInfoInExample=false

Node.jsモジュールとして実行する例:

const fs = require('fs'),
  Converter = require('openapi-to-postmanv2'),
  openapiData = fs.readFileSync('oas.yaml', {encoding: 'UTF8'});

Converter.convert({ type: 'string', data: openapiData },
  {}, (err, conversionResult) => {
    if (!conversionResult.result) {
      console.log('Could not convert', conversionResult.reason);
    }
    else {
      console.log('The collection object is: ', conversionResult.output[0].data);
    }
  }
);

Postman APIとは？

Postman APIは、Postmanクラウド上のPostmanアセットを管理・操作するためのAPIです。Postman APIを使用することで、Postmanアセットをプログラムで簡単に操作し、開発ツールチェーンに統合することができます。

Postmanアセットには、Postmanワークスペース、コレクション、環境、モニター、モックサーバーなど、Postmanアプリで操作する様々なデータが含まれます。APIの詳細については、下記のPostman APIリファレンスを参照ください。

実際にPostman APIを試してみる際は、パブリックに公開されているPostman API用コレクションがあるので、それをフォークしてご自身のワークスペースでお試しいただくのが良いでしょう。

コレクション更新用APIリクエスト設定ページのイメージ：

Screenshot_2024-05-13_at_1.36.51.png

OpenAPIを元にコレクションを新規作成

それでは、本題であるOASを元にPostmanコレクションを新規作成する手順をご紹介します。手順は以下の2つのステップになります。

  1. openapi2postmanを使用してOASデータからPostman コレクションデータを生成
  2. 生成したコレクションデータを元に、Postman APIを使用して新規のコレクションを作成

なお、本記事ではOASのサンプルとしてPetstore OpenAPI Spec 3.0を使って説明をすすめます。

(1) OASデータからPostman コレクションデータを生成

まずは、サンプルのOASファイルをoas.jsonという名前でダウンロードします。

curl -o oas.json https://petstore3.swagger.io/api/v3/openapi.json

つづいて、openapi2postmanツールで、oas.jsonを元にPostmanコレクション（collection.json）を生成します。

# install openapi2postman (もしインストールまだなら)
# ここではglobalにインストール。ローカルならば -gオプションはずす
npm install -g openapi-to-postmanv2

# openapi2postmanでoas.jsonからPostmanコレクション（collection.json）を生成
openapi2postmanv2 -s ./oas.json \
    -o collection.json -p \
    -O folderStrategy=Tags,parametersResolution=Example,enableOptionalParameters=false

引数の説明

  • -s <file> (または --spec <file>): インプットするOASファイルのパス
  • -o <file> (または --output <file>): 出力されるPostmanコレクションファイルのパス
  • -p (または --pretty): ファイルへの書き込みをプリティに(整形)する
  • -O <options> (または --options <options>): OASからPostmanコレクション生成のためのオプション。ここでは、下記の内容で生成オプションを指定。詳細はこちらのページを参照ください

OASからPostmanコレクション生成のためのオプション

  • folderStrategy=Tags: OASのパスに従ってPostmanコレクションのフォルダを作成するか、タグに従ってフォルダを作成するかを選択。PathsまたはTagsが選択可能で、ここではTagsを選択
  • parametersResolution=Example: OASのschemaに基づいてリクエストパラメーターを生成するか、スキーマのexample例に基づいてパラメーターを生成するかを選択。SchemaかExampleが選択可能で、ここではExampleを選択
  • enableOptionalParameters=false: OASでrequired:trueで指定していないオプショナルなパラメーターはコレクションのAPIリクエスト設定のパラメーターで明示的にチェックなしにする（選択されていない状態にする）。デフォルトはtrueで、パラメーターが明示的にチェックされるようになる

補足: openapi-to-postmanのバージョンと利用可能なオプションについて

openapi-to-postman (default v2)のバージョンが4.22.0もしくはそれ以下の場合、v1でのみサポートされるオプションを利用できたが、4.23.0以降のバージョンでは利用できなくなっているので注意が必要となります。例えば、4.23.0以降のバージョンでは利用できなくなったものに以下のオプションが挙げられます:

  • collapseFolders
  • optimizeConversion
  • requestParametersResolution
  • exampleParametersResolution

オプションに関する詳細はこちらのページを参照ください

なお、上記の処理で得られるコレクションデータ(json)は次のようになります。

collection.json
{
  "item": [
    {
      "name": "pet",
      "description": "Everything about your Pets",
      "item": [ "...内容省略..." ]
    },
    {
      "name": "store",
      "description": "Access to Petstore orders",
      "item": [ "...内容省略..." ]
    },
    {
      "name": "user",
      "description": "Operations about user",
      "item": [ "...内容省略..." ]
    }
  ],
  "event": [],
  "variable": [
    {
      "key": "baseUrl",
      "value": "/api/v3"
    }
  ],
  "info": {
    "_postman_id": "45badc05-a0d1-41dd-ab31-77d16c26e338",
    "name": "Swagger Petstore - OpenAPI 3.0",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
    "description": {
      "content": "This is a sample Pet Store Server based on the OpenAPI 3.0 specification.  You can find out more about\nSwagger at [http://swagger.io](http://swagger.io). In the third iteration of the pet store, we've switched to the design first approach!\nYou can now help us improve the API whether it's by making changes to the definition itself or to the code.\nThat way, with time, we can improve the API in general, and expose some of the new features in OAS3.\n\nSome useful links:\n- [The Pet Store repository](https://github.com/swagger-api/swagger-petstore)\n- [The source API definition for the Pet Store](https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml)\n\nContact Support:\n Email: apiteam@swagger.io",
      "type": "text/plain"
    }
  }
}

(2) 1で作成したコレクションデータを元にPostman APIを使って新規コレクションを作成

Postman APIの コレクション作成APIを使って作成します。

  • APIエンドポイント: https://api.getpostman.com/collections
  • クエリパラメーター: (任意) workspace=＜ワークスペースID＞
    • ＜ワークスペースID＞: コレクションの作成先のワークスペースのID。ワークスペースIDの指定は任意であり、このクエリパラメーターを含めない場合、システムは My Workspace にコレクションを作成します
  • HTTPメソッド : POST
  • ヘッダー:   X-API-Key: <Postman APIキー>

上記で取得したコレクションデータの中身を コレクション作成APIのリクエストボディに下記のフォーマットでセットします。

{
  "collection": {
     "...(1)で取得したコレクションデータの中身..."
   }
}

今回サンプルとして使用したPetstoreコレクションのデータで新規作成する場合、リクエストボディは次のようになります。

{
  "collection": {
    "item": [
      {
        "name": "pet",
        "description": "Everything about your Pets",
        "item": [...omit...]
      },
      {
        "name": "store",
        "description": "Access to Petstore orders",
        "item": [...omit...]
      },
      {
        "name": "user",
        "description": "Operations about user",
        "item": [...omit...]
      }
    ],
    "event": [],
    "variable": [
      {
        "key": "baseUrl",
        "value": "/api/v3"
      }
    ],
    "info": {
      "_postman_id": "45badc05-a0d1-41dd-ab31-77d16c26e338",
      "name": "Swagger Petstore - OpenAPI 3.0",
      "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
      "description": {
        "content": "This is a sample Pet Store Server based on the OpenAPI 3.0 specification.  You can find out more about\nSwagger at [http://swagger.io](http://swagger.io). In the third iteration of the pet store, we've switched to the design first approach!\nYou can now help us improve the API whether it's by making changes to the definition itself or to the code.\nThat way, with time, we can improve the API in general, and expose some of the new features in OAS3.\n\nSome useful links:\n- [The Pet Store repository](https://github.com/swagger-api/swagger-petstore)\n- [The source API definition for the Pet Store](https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml)\n\nContact Support:\n Email: apiteam@swagger.io",
        "type": "text/plain"
      }
    }
  }
}

以下は、Node.jsでこのリクエストを送信するためのサンプルコードです。axiosライブラリを使用しています。

const axios = require('axios');
let data = JSON.stringify({
  "collection": {"コレクションJSONデータ"}
});
let workspaceID = "ワークスペースID";
let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.getpostman.com/collections?workspace=' + workspaceID,
  headers: { 
    'Content-Type': 'application/json', 
    'X-API-Key': '<Postman APIキー文字列>'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

上記の内容のリクエスト送信が成功すれば、指定したワークスペースにコレクションが新規に作成されます。コレクションのサイズが大きければ大きいほど作成に時間がかかるのでご注意ください。

💡 補足

OASを元にPostmanコレクションを新規作成するのに次の2つのPostmanAPIが活用できます：

本記事ではコレクション更新方法との統一感を加味してコレクション作成APIを活用してます

Postman APIを活用して既存のコレクションを更新

OASを元に既存のPostmanコレクションを更新する手順は、新規コレクション作成とのほぼ同じで、次の２ステップになります。

  1. openapi2postmanを使用してOASデータからPostman コレクションデータを生成
  2. 生成したコレクションデータを元に、Postman APIを使用して既存コレクションを更新

(1)はコレクション新規作成のと全く同じなので省略します。ここでは(2)のみ紹介します。

先に(1)で生成したコレクションデータを元に、Postman APIの コレクション更新APIで、既存のコレクションを更新します。

  • APIエンドポイント: https://api.getpostman.com/collections/＜コレクションID＞
    • ＜コレクションID＞: 更新対象である既存のコレクションID
  • HTTPメソッド : PUT
  • ヘッダー:   X-API-Key: <Postman APIキー>

リクエストボディはコレクション新規作成APIと同じで次のフォーマットになります。

{
  "collection": {
     "...(1)で取得したコレクションデータの中身..."
   }
}

以下は、Node.jsでこのリクエストを送信するためのサンプルコードです。

const axios = require('axios');
let data = JSON.stringify({
  "collection": {"コレクションJSONデータ"}
});
let collectionID = "コレクションID";
let config = {
  method: 'put',
  maxBodyLength: Infinity,
  url: 'https://api.getpostman.com/collections/' + collectionID,
  headers: { 
    'Content-Type': 'application/json', 
    'X-API-Key': '<Postman APIキー文字列>'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

上記のリクエスト送信が成功すれば、指定した既存のコレクションが更新されます。コレクションのサイズが大きければ大きいほど更新に時間がかかるのでご注意ください。

おわりに

本記事では、openapi-to-postmanとPostman APIを活用して、OASを元にPostmanコレクションの作成・更新を自動化する方法を紹介しました。これまで何度かOASを元にPostmanコレクションの作成・更新を自動化する方法について質問をいただいたので記事にまとめてみました😁

なお、OASを元にしたPostmanコレクション作成・更新において、新しい機能要望や既存の機能に対して変更要望などがでてくるかもしれません。今回紹介したopenapi-to-postmanはOSSですし、OpenAPIとPostmanコレクションのフォーマットは共に標準フォーマットとして公開されています。よって、その場合は、ご自分で改良や機能追加も可能ですし、興味があれば好みのツールを作ることも可能かと思います。ぜひ挑戦してみてください。

APPENDIX

PostmanアプリでOpenAPIを元にコレクションを新規作成（インポート）

PostmanアプリでOpenAPIからコレクションを作成する方法を紹介します。

既存のOpenAPI 3.0と3.1の定義（OpenAPI仕様）をPostmanにインポートできます。PostmanはYAMLとJSONの両方のフォーマットをサポートしてます。

API定義をPostmanにインポートするには、サイドバーのインポートを選択します。すると、次のようなインポート用のモーダルが立ち上がります。

Screenshot_2024-04-21_at_16.46.13.png

API定義はローカルのファイルやディレクトリ、URL、生のJSONやYAMLといったテキストからインポートできます。API定義を指定すると、次にインポート方法の選択をします。

Screenshot_2024-04-21_at_16.46.31.png

「Postman Collection」は定義をコレクションとしてインポートします。こちらを指定すると、次のようにOpenAPIを元にPostmanコレクションが作成されます。

Screenshot_2024-04-21_at_17.34.39.png

一方、「OpenAPI 3.0 with a Postman Collection」はコレクションとともにAPI定義も一緒にインポートするかを選択できます。これはAPIビルダーと呼ばれる機能で、詳しくは「Design your API in Postman using the API Builder」ページを参照ください。

Screenshot_2024-04-21_at_17.24.43.png

また、View Import Settings（インポート設定を表示）を選択すると、その他の設定オプションが表示されます。これらのオプションの詳細については、こちらのページを参照ください。

7
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
7
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?