【Golang】APIMATIC で Postman Collection を OpenAPI Specification に変換する
PostmanはOpenAPIと互換性があり、OpenAPI Specification(以下OAS)に沿って書かれたAPIドキュメントはPostmanへimportできる。一方で、PostmanからOpenAPIへのexportはサポートされていない。これはPostmanへのFeature requestとしても挙がっており、そこそこ支持を得ている様子ではあるものの、3年前に提案されてからも未だに導入されていない。
Postmanを使ってAPIクライアントとのコミュニケーションを取りたいが、ドキュメントとして見た場合一部痒いところに手が届かない部分がある(BodyのDescription/Schemaを記述できないなど)。そのため、Postmanで記述したAPI仕様をOASに落として、管理は煩雑になるが仕様をより詳細に載せたverを作成できないかと考えた。
そこで、3rd partyから変換可能なものがないか探してみた。
Postman Collection -> OAS 変換可能な3rd partyのツール/サービス
stoplightio/api-spec-converter
Spotlight.ioでも使用されているライブラリ。Postman Collection v1のみ対応。
JSライブラリのため、変換用のコードをJSで記述する必要がある。ただ実際に変換を検証したところ、v1形式のPostman Collectionを変換しようとしたが、うまく変換できなかった。。。
また、3年前ほど前から保守がストップしている。そのため今回は使用を見送り。
APIMATIC
APIMATIC社が提供するSaaS。Postman Collection v2の変換に対応している。
アカウント登録が必要だが、結果から言うとドキュメント変換がきれいに実行できた。今回はこのツールを使用してみる。
APIMATICで Postman Collection を OASに変換する
はじめに、Postman上に定義されたAPI仕様をexportする。
exoprtしたいCollectionの三点リーダをクリックし、出現したリストの Export をクリックする。
するとexportするファイルのバージョンを選択できるので、ここではv2.1を選択。
これで、 Postman Collection と呼ばれる json ファイル形式のAPIドキュメントが出力される。
このファイルはPostman間の定義や設定共有に使用されるものだが、今回はその中のAPI定義部分を抽出し、OASとして変換する。
次に、 APIMANICのWebページを開き、 Sign Up for free をクリック。
新規アカウント登録画面に遷移するので、必要な情報を入力し、 Sign Up をクリック。
しばらくすると登録したメールアドレスにconfirmメールが来るので、メール内のconfirmボタンをクリックし、 Click here をクリックする。
APIMATICダッシュボード画面に遷移する。 Transform API をクリック。
先程exportした Postman Collection jsonファイルを選択し、 好きな形式を選択してexportできる。今回はOAS3.0を選択。Convertボタンをクリック。
最後にうまく変換できたかどうかが表示されるので、確認した上でProceedボタンを押して変換後ファイルをダウンロード。
完了。
以下のようなOAS3.0形式ファイルが出力される。
openapi: 3.0.0 info: title: test contact: {} version: '1.0' servers: - url: http://hoge.api.com variables: {} paths: /test: get: tags: - Misc summary: http://hoge.api.com/test description: http://hoge.api.com/test operationId: http://hoge.api.com/test parameters: [] responses: 200: description: '' headers: {} deprecated: false tags: - name: Misc description: ''
これで、 OpenAPI形式への変換が完了した。
これでOASに合わせて記述を追加したり、OAS対応のサービスでおしゃれにレンダリングしたりできる。
