APIを開発する時、Swagger を使用し、API定義資料に Swagger Spec ファイルを使用するケースも多いかと思います。
便利なのですが、SwaggerHub に課金していないとチーム開発では使いづらかったり、「えー。Postman の方が好きなのに、こっちにも課金しないといけないの？」という感覚が出てきたりします。
ただ、Postman には Swagger Spec ファイルを読み込ませる事ができるので、いったん Swagger Editor で作成した Swagger Spec ファイルを Postman にインポートして、続きは Postman を使って開発を進める、といった運用が可能です。
ちなみに Postman はアプリ版とブラウザ版があり、今回はブラウザ版を使用しています。
備考
| 用語 | 説明 |
|---|---|
| Swagger | REST APIを構築するためのオープンソースのフレームワーク |
| Swagger Spec | APIの挙動をまとめたドキュメント。YAML または json で記述 |
| Postman | Web API開発支援ツール。パラメータをセットして、好きにリクエストを投げたりできる。 |
| Swagger Editor | Swagger Specの設計書を記載するためのエディタ。別にこれがなくても書けるけど、YAMLファイルを編集して記述していくのは、なかなかしんどい。 |
Swagger Spec ファイルをインポート
1．「import」ボタンを押下
２． Swagger Spec ファイルを選択
「Upload File」ボタンを押下し、ファイルを選択。
ドラッグ＆ドロップでも可。
ファイル選択後「import」
ファイルを正常に読み込ませる事ができたら、「close」
３． 完了
こんな感じで、Postman での操作ができるようになっています。
Swagger Spec ファイルをエクスポート
「Postman を使って開発を進めるも、最終的には Swagger Spec ファイルの納品が必要」という状況の場合、Postman から Swagger Spec ファイルを出力する機能があったりします。
1．「Export」ボタンを押下
操作は簡単。「Export」ボタンを押して、ファイルを保存するだけ。
エクスポートについての注意点
ただし、2021年 4月時点において、出力できる Swagger Spec ファイルは json 形式のみのようです。
YAMLファイルが必要な場合、出力した json ファイルから YAMLファイルにコンバートする必要があります。
Webサービス：JSON to YAML
ブラウザにコピペするだけで、json を yaml に変えてくれる。
https://www.json2yaml.com/
使い方は超簡単。
「JSON」の枠に、コピペするだけ。
VSCodeプラグイン：json2yaml
プラグインをインストールした後、「command + p」で操作ウィンドウを表示させた後、「>convert」と入力すると、『Convert Json to YAML』が出てくるので、それを選択。
が、少し複雑な Swagger Spec ファイルは正しく解析してくれないケースもありました。
あと、description が変に長いと、形が少し崩れたりします。
とはいえ、ローカルで手軽に動かす事ができるのは便利なので、普段は json2yaml を使い、そっちでカバーしきれない部分は JSON to YAML を使う、というスタイルで良いのでは無いでしょうか。
とりあえず、Postman が YAML ファイルをエクスポートできるように機能拡張してくれる事を期待。
このエントリを書く前にも、色々と実験してたりしますので、よろしければそれらもご参考頂けると幸いです。
コメント