PostmanのCollectionsで管理されていたドラフトのAPI仕様をOAS形式に変換してみた

MADグループ@大阪の岩田です。タイトル通りなのですがPostmanのCollectionsで管理作成されていたAPI仕様をOAS形式に変換してみたので手順やポイントをご紹介します。

環境

今回利用した環境です

• Postman: 9.30.4
• postman-to-openapi: 2.3.0

移行手順

以下の手順でPostmanのCollection形式からOAS形式への変換を行い、API仕様の管理方式を移行していきました。

初期のCollectionsの状態

まず初期段階は以下のような状態でした。PostmanのCollectionsにドラフトのAPI仕様がいくつか作成されており、exampleも作られていました。これらをOAS形式に変換していきます。

Collectionsをエクスポート

まずCollectionsに作成されたAPI仕様をエクスポートします。エクスポートしたいCollectionのメニューからExportを選択します。

どの形式でエクスポートするか確認されるので、Collection v2.1を選択して Exportをクリックします。

保存先を選択するダイアログが表示されるので適当な場所を選択してエクスポートを続行します。エクスポートが完了すると指定したディレクトリに以下のようなJSONファイルが出力されます。

{
  "info": {
    "_postman_id": "b0988364-bcfd-4caf-88bd-0f90b6f0f82c",
    "name": "Petstore",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
    "_exporter_id": "4482317"
  },
  "item": [
    {
      "name": "Add a new pet to the store",
      "request": {
        "method": "POST",
        "header": [],
        "url": {
          "raw": "{{baseUrl}}/pets",
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "pets"
          ]
        }
      },
      ...略

postman-to-openapiでフォーマットを変換

続いてエクスポートしたファイルをOAS形式に変換します。Postmanの公式ドキュメントを確認したところ、postman-to-openapiというツールが紹介されていたので、このツールを使って変換してみます。npxからサクっと以下のコマンドを実行します。

$ npx postman-to-openapi <先程エクスポートしたJSONファイル> -f <変換後のOAS形式のファイルパス>

変換結果が標準出力に表示されつつ、コマンドライン引数で指定したパスに変換後のYAMLファイルが出力されます。

openapi: 3.0.0
info:
  title: Petstore
  version: 1.0.0
servers:
  - url: http://{{baseurl}}
paths:
  /pets:
    post:
      tags:
        - default
      summary: Add a new pet to the store
...略      

フォーマット後のファイルをPostmanにインポート

フォーマットが変換できました。今後Postmanは使わないのであればここで作業完了なのですが、諸々のテストにPostmanは継続して利用したいので、変換後のファイルを再度Postmanにインポートしてみます。

PostmanのメニューからAPIsを選択し、Importをクリックします。

インポート対象ファイルを選択するダイアログが表示されるので、先程変換したOAS形式のファイルを選択します。

確認画面に進むので、そのままImportを選択します。この際Generate collection from imported APIsを選択しておくことでOASのAPI仕様を元にPostmanのCollectionsが自動生成されます。

しばらく待つとインポート完了画面が表示されます。

Collectionsを確認すると、元々存在したCollectionに加えてOAS形式のファイルをインポートした際に自動生成されたCollectionが追加されていることが分かります。このコレクションを利用すれば従来通りPostmanを利用したテストも可能です。元々存在したCollectionsは不要になったので削除しておきましょう。

OASのエラーを潰す

これでインポートは完了しましたが、元々のexampleの設定内容次第ではいくつかエラーが出ることがあります。今回の例だと

• responses直下のキーがundefinedとなっている
• responsesの定義にdescriptionが設定されていない

といったエラーがあります。

適宜エラーを修正して保存しておきます。

API仕様の修正をCollectionsに反映する

ここまででAPI仕様のフォーマットを変更しつつ、PostmanのCollectionsもこれまで通り利用できる状況に持っていけました。が、APIの仕様はまだドラフトであり、今後もガンガン修正が入っていく予定です。Collectionsの中身をAPI仕様の変更に追随させる方法も確認しておきましょう。

OAS形式のAPI仕様を修正する

元々POST /petsのリクエストボディを特に定義していなかったところに新たに定義を追加したとします。まずPostmanのAPIsメニューからDefinitionタブでAPI定義を編集します。

編集後にOverviewタブのDocumentationからNo Issues foundをクリックします

Validate Againというボタンが表示されるので、これをクリックして編集後のAPI仕様を検証します。

issues foundと表示されるのでクリックします

Review Issuesをクリックし問題点を確認します

新たに追加したAPI仕様とCollectionsの同期が取れていないことが分かります。Select all changesを選択し、Confirm Changes to Collectionをクリックしましょう

しばらく待つと同期完了のメッセージが表示されます

OASの定義から生成されたCollectionの中身を確認するとAPI仕様の変更が反映されたことが分かります。

これでAPI仕様とCollectionsの同期もある程度対応可能です。注意点としてAPI仕様の変更がCollections内の全ての項目に反映される訳ではないので、そこは頭に置いておく必要があります。

今回の例だとPOST /postsのレスポンスサンプルにはリクエストボディの定義変更が反映されません。各requestのexampleについてはある程度自分で手動メンテナンスすることも考慮にいれておきましょう。自動生成されたもの以外に手動作成したrequestやexampleが存在しなければ、Collectionを丸々削除してしまって、再度API仕様からCollectionを自動生成させてしまうのが楽だと思います。

まとめ

個人的にPostmanはAPIクライアントの用途としてしか使ってこなかったのですが、API仕様を管理するツールとしても使えて便利だなと感じました。API仕様はStoplight Studioで編集しつつ、完成したAPI仕様はPostmanにインポートして...といったように、各ツールの強みをうまく組み合わせて自分なりの生産性の高い方法を確立していければと思います。

参考

• Postman Open Technologies - Convert Postman Collections Into OpenAPI
• postman-to-openapi