調べたきっかけ
よくあるイマドキ(?)のAPI仕様書の見え方として、↓下記の二つがありますよね。
現職では前者を「Swagger」と呼んでいますが、いや前職で後者みたいな緑ヘッダのやつのことも「Swagger」って呼んでたな...とふと疑問に思いました。
そこでSwaggerとOpenAPI周りの用語を調べてみて、何が何を指しているのかを自分なりにまとめてみたので、紹介させて下さい。
3カラムHTMLファイルのやつ
緑ヘッダのやつ(Swagger-UI)
Swagger/OpenAPIとはそれぞれ何か
| 用語 | 意味 |
|---|---|
| Swagger | RESTful APIの仕様文書化を助けてくれるオープンソースのツール群 またはRestful APIの仕様をymlまたはjsonで記述する書き方のこと |
| OpenAPI | Restful APIの仕様をymlまたはjsonで記述する書き方のこと |
Wikipediaだと「機械可読インターフェースファイルの仕様」とか書かれてて意味わからんので多少は自分なりに噛み砕いて書いてます。
歴史的な話
この歴史が呼び方をワケわからんくしている
- 2010年、Wordnik社（オンライン辞書会社)がSwagger仕様の開発開始
- 2015年、SmartBear社がWordnik社からSwagger使用を取得（買収的な？）
- 同年、SmartBears社はOpenAPIイニシアチブと呼ばれる組織を作ると宣言
- 2016年、Swagger仕様はOpenAPI仕様に名前が変更される
引用元はこちら
「書き方」っていうけど具体的にはどんなん？
ymlファイルの頭がopenapi: 3.0.1で始まるかswagger: 3.0.0で始まるかで変わる。
細かい仕様の違いは略
冒頭の2つの見え方は何が違う？
緑ヘッダのやつ
緑ヘッダのやつはSwagger-UIというライブラリを使って出力されます。
Swagger-UIはnodejsを用いてサーバ上でHTMLで出力されます。
サーバ上で見えるので社内で使う分には(IP制限などかけて)便利ですが、そのまま社外にAPI仕様書として提供するのは少し難しいかもしれません。
3カラムHTMLファイルのやつ
ymlファイルを元にRedocというライブラリを使って出力されます。
HTMLファイルとして使えるので、お客さんに渡したり、対外的にも使いやすいのがメリットかと思います。