🐷

Insomniaを使ってOpenAPI(Swagger)仕様書を作る

2023/08/28に公開

Stoplight Studioは臨終しました

API仕様書作成で過去にいくつか記事を書いた。
API Blueprintを使っていたが、
ツールが老朽化したのでSwaggerに切り替えたのだが、
Swaggerの仕様書作成で使っていたStoplight Studioというツールが有償化して結構な高額商品となった。
($39/month)

ちょっと非現実な価格なので別のものを探し始める。

(((((((((((っ･ω･)っﾌﾞｰﾝ

insomniaというのがあるらしい。

無料プランでほとんどのことができるっぽいから、
気軽に使えるのがいいな。

insomniaにはプラグインが色々あり、
その中にSwagger出力プラグインもあるのだが、
動作がもう一つなので、
ここでは別のツールを使う。
それが swaggomnia
コマンドラインでinsomniaファイルをswagger用jsonまたはymlに変換する

早速使ってみよう。

ヾ(・ω<)ﾉ"　三三三●　ⅱⅲ コロコロ♪

------------------- ↓ 本題はここから ↓-------------------

以下よりダウンロード。
インストーラーを起動してインストールする

マニュアルを駆使して、
API仕様(Collection)を作成する

以下より該当OSのバイナリをダウンロード。
パスの通る位置に実行ファイルを置く。

予め設定ファイルが必要なので以下のファイルを作成しておく

swaggomnia.json

{
  "title" : "API Name",
  "version" : "API version",
  "basePath" : "https://api.domain.com/v1",
  "description" : "API description"
}

実行コマンドは以下の通り

swaggomnia.exe generate --insomnia Insomnia_2023-08-22.json --config swaggomnia.json  --output yaml

swagger.yml というファイルをが出来上がるので、
VSCode(Swagger Plugin)などで開いてみる。

------------------- ↓ 後書きはここから ↓-------------------

これでもいいけどなぁという点があって、
APIテストが主眼なだけあって、
スキーマ定義がなかったりする。
(探しきれてないだけかもしれないが)
なので、API仕様書として使うにはもう一歩かなぁという印象。

ここまで書いた段階で別のツールを発見。
今度はこちらを使ってみよう。