OpenAPI / Swagger overview

動機

"APIのインタフェースをSwaggerを使って定義しておきますね"

何を言っているのかわからなかった。

やりたいこと

Swaggerで何ができるのか、何をしたいから使うのか、どうやって使うのかを知りたい。

やったこと

• swaggerのドキュメントを読んで理解するために必要そうなところをまとめた
• OpenAPIのフォーマットにそってAPIを定義してみた

Swaggerとは

swagger.io

Swagger is the most widely used tooling ecosystem for developing APIs with the OpenAPI Specification (OAS).

API開発のためのエコシステム、なるほど。OpenAPI Specifiactionがわからない。

OpenAPI Specificationとは

おそらく知りたかったのはこっち。

swagger.io

RESTful APIのためのインタフェース。サービスの提供するものを、

• 人にもコンピュータにも検索・理解がしやすい形で
• ソースコード・ドキュメント・ネットワークトラフィックにアクセスせずに
• 検索・理解することができる

OpenAPIの定義は様々な用途に使うことができる。

• APIドキュメント生成
• 様々な言語でサーバ・クライアントの生成

仕様があればドキュメントを生成することもできるし、簡単なサーバ・クライアントを自動で作ることもできるということ？できそう。

つまりOpenAPIはAPI仕様を定義するためのフォーマットということ。

OpenAPIの仕様

フォーマット

JSONもしくはYAMLで書かれる

ドキュメント構造

複数のファイルに分割することができ、どちらにするかは自由。 分割する場合は、$refフィールドによって参照する。

分割した場合、ルートとなるファイルはopenapi.jsonまたはopenapi.ymlとすることが推奨されている。

OpenAPIとSwaggerの違い

結局Swaggerが何かわからなくなった。 公式ドキュメントのA Brief History Lessonのセクションによると

• SwaggerというAPIの仕様記述のフレームワーク・エコシステムが存在した
• 2015年にLinux Foundationに寄付されOpenAPI Specificationという名前に変更
• Swaggerの書式をベースにしてAPI記述フレームワークの標準を策定するための団体であるOpenAPI Initiative (OAI)が設立
• 現在はOpenAPIを記述するためのツールが他にも存在している

Swaggerをベースに標準規格であるOpenAPIの仕様が決められたけど、OpenAPIを記述するためのフレームワークはSwagger以外にもあるよということらしい。

www.publickey1.jp

現在でSwaggerといったらOASを記述するためのツールという意味合い？

qiita.com

チュートリアル

OpenAPIのフォーマットでAPIの仕様を書く。

良さそうだったのでVSCodeのSwagger Viewerを使いながら書いてみる。良さそうというのは書いたyaml/jsonをいい感じに見せてくれるのでわかりやすそうだった。

インストールは以下を参考にして行った。

qiita.com

最小構成

ドキュメントでrequiredとなっているフィールドは埋めないと描画してくれないので注意。 OASの仕様に載っている例を流し込んだ。openapiのバージョンはよくわからなかったので適当に設定した。

左でyamlを書いて右でそれをいい感じに見せてくれる。