いい感じにOASファイルとPostmanを連携する
概要
リポジトリにあるOAS(OpenAPI Specification)ファイルとPostmanをいい感じに連携する
OASとは
OpenAPI Specificationの略で、REST APIを記述するためのフォーマット
yaml形式あるいはjson形式に対応している
Postman
APIの作成、利用するためのプラットフォーム
去年くらいから日本語対応し始めている
対象の読者
- OASでAPI仕様書を管理していて、PostmanでAPIを実行している
- OASファイルをPostmanにいちいちインポートするのしんどい
- OASファイル編集したらPostmanにも反映されていてほしい・・・
- ゆくゆくはPostmanコレクションを公開したい・・・
結論
いろいろ悩んだ結果、以下に落ち着いた
- OASファイルをPostman形式に変換
- PostmanAPIを使ってコレクションを更新する
参考にした上記記事はnode.jsでコードを書いているが、自分はシェルスクリプトでなんとかした
※GitHub Actions使いたいけど業務の都合上、まだできるアレじゃない
以下、いろいろ解説
なぜPostmanAPI?
なぜPostmanAPIを使ってコレクションの更新をすることになったかというと、コレクションの更新の機能はAPIでの提供のみだったため。
Postmanでは、OASファイルをインポートすることでコレクションを追加することができる機能があるのだが、この機能はコレクションを新規追加するのみで更新することができない。
仮にコレクションを外部公開することになると、APIの更新のたびにコレクションが書き変わることになって、外部の人がまともにフォークもできない状態になる。
それは避けたかったので、PostmanAPIで更新することにした。
また、PostmanはGitHubとの連携も可能ではあるが、GitHub連携はブランチ切ったりプルやプッシュといった基本的なgitの機能を使ってAPIの編集ができるものの
APIタブ内での連携にとどまっており、コレクションとの連携はできない。
つまり、OASファイルインポートと同じようにコレクション更新ができないのでGitHub連携は見送った。
Postmanへの反映手順
OASファイルをPostman形式に変換
Postman形式に変換するためには、Postmanが提供しているコマンド openapi-to-postmanv2 を利用する
インストール
$ npm install openapi-to-postmanv2
実行
# -OはPostman形式にする際のオプション
$ npx openapi2postmanv2 -s ./openapi.yaml \
-o ./postman-collection.json -p \
-O folderStrategy=Tags,requestParametersResolution=Example,optimizeConversion=false,enableOptionalParameters=false
PostmanAPIを使ってコレクションを更新する
以下のようにコレクションIDとAPIKeyを取得して、APIを投げる。
## APIに必要な情報
### コレクションID
collectionId="{collectionId}"
### API Key
APIKey="{APIKey}"
### リクエスト
collection=$(cat ./postman/collection.json)
request="{""collection"": ${collection}}"
## postman形式をpostmanAPIに投げる
curl --location --globoff --request PUT "https://api.getpostman.com/collections/${collectionId}" \
--header "Content-Type: application/json" \
--header "X-API-Key: ${APIKey}" \
--data @- << _RequestBody_
{
"collection": ${collection}
}
_RequestBody_
こんな感じで更新日時が更新されたらOK
PostmanAPIについてはこちら
参考
Discussion