まじで簡単にOpenAPIとSwaggerについてまとめておいた

2022年11月9日

はじめに

前の会社で他のチームがSwaggerを使用してAPI設計をしっかりと行なっているのを横目で見ていた。

が、遂に自分もSwaggerとかOpenAPIとなるものに触れる機会がきた。
この機会にしっかりと習得してしまおうと思っている。

そもそも、OpenAPIとかSwaggerってなんなのかわかっていなかったので、自分なりに調べて解釈した内容をここにまとめておこうと思う。

超ざっくり書きますが、おかしな点がありましたらご指摘お願いします。

OpenAPIというものは、フォーマットのことを意味するらしい。このフォーマットを使用すると、機会が読めるAPIの仕様を記述することができる。このフォーマットは、XMLもしくはYAMLで記述をする。YAMLで記述されているのが一般的というか、多いっぽい。

では、Swaggerとはなんなのか。

Swaggerは、OpenAPIを作成したり、表示したり、利用したりするためのツール群のことを意味するらしい。

ツール群になるので、いくつかツールが存在する。

ツール名	概要
Swagger Editor	OpenAPIを記述するためのエディターのこと
Swagger Codegen	Swagger Editorで生成されたOpenAPIを読み取ってソースコードを生成してくれたりする
Swagger UI	OpenAPIを読み取り、仕様書として表示してくれる

こういうものがあるらしい。

ちょっととっかかりは難しそうに感じるが、調べてみるとなんとなくわかる。

実際にOpenAPIを書いてみると、なんとなくできたし、がんばろう。