読者です 読者をやめる 読者になる 読者になる

5分くらいでわかるSwagger

最近身の回りでSwaggerを聞くことが多くなってきたと感じます。

上記記事でも言及されていますが、AWS API Gateway Importerでも、APIAPI GatewayにインポートするためのAPIの入力仕様としてSwaggerが使われています。
私もちょっと前から、AWS API Gatewayを使ってます。API GatewayAPIを作成するにあたり、GUIからポチポチAPIを作っていくのが辛いというのは多くの人の共通認識だと思うので、AWS謹製のインポータを使うのが今のところは最善の選択だと実感しています。

というわけで、Swaggerについての簡単なまとめ資料みたいなものを作りました。

Swaggerで調べると、Swagger codegenやSwagger UIをメインにした記事は多いのですが、Swagger Specificationの書き方そのものについて紹介している記事って少ないなぁと感じたので、その辺を意識して作りました。とはいえ、Swagger Specificationの構文はシンプルであり、公式ドキュメントも丁寧なので、5分くらいでざっくり分かる、というレベルにしています。

スライドでは触れていないですが、Swaggerの場合、'x-'で始まる独自の拡張項目を使うこともできて、AWS API Gateway Importerの場合、 x-amazon-apigateway-auth, x-amazon-apigateway-integration がそれに該当します。
これらについては、資料の趣旨が変わるので、別の機会にまとめようかと思います。

追記

Swaggerの周辺ツールとして、SpringのアノテーションからSwagger Specification(JSON)を生成するSpringFoxというものがあることを知りました。