調べたきっかけ

よくあるイマドキ(?)のAPI仕様書の見え方として、↓下記の二つがありますよね。
現職では前者を「Swagger」と呼んでいますが、いや前職で後者みたいな緑ヘッダのやつのことも「Swagger」って呼んでたな...とふと疑問に思いました。

そこでSwaggerとOpenAPI周りの用語を調べてみて、何が何を指しているのかを自分なりにまとめてみたので、紹介させて下さい。

Swagger/OpenAPIとはそれぞれ何か

用語	意味
Swagger	RESTful APIの仕様文書化を助けてくれるオープンソースのツール群またはRestful APIの仕様をymlまたはjsonで記述する書き方のこと
OpenAPI	Restful APIの仕様をymlまたはjsonで記述する書き方のこと

Wikipediaだと「機械可読インターフェースファイルの仕様」とか書かれてて意味わからんので多少は自分なりに噛み砕いて書いてます。

この歴史が呼び方をワケわからんくしている

引用元はこちら

ymlファイルの頭がopenapi: 3.0.1で始まるかswagger: 3.0.0で始まるかで変わる。
細かい仕様の違いは略

緑ヘッダのやつはSwagger-UIというライブラリを使って出力されます。
Swagger-UIはnodejsを用いてサーバ上でHTMLで出力されます。

サーバ上で見えるので社内で使う分には(IP制限などかけて)便利ですが、そのまま社外にAPI仕様書として提供するのは少し難しいかもしれません。

ymlファイルを元にRedocというライブラリを使って出力されます。

HTMLファイルとして使えるので、お客さんに渡したり、対外的にも使いやすいのがメリットかと思います。