Swaggerを使ってAPI仕様書を書く！

先日、Swaggerというフレームワークを利用して作成されたAPI仕様書を初めて見たが、使い方や見方がさっぱり分からなかったため、
備忘録の意味でも学習内容を記載いたします。

今回、サンプルや参考サイト等を見て記述したyamlファイルは下記リポジトリに存在します。

https://github.com/mashharuki/Swagger_Practic

Swaggerとは？
REST APIを定義するためのフレームワークのこと
(別の方は、ツールセットとも表現されていました。)

REST APIとは？
RESTの原則に則って構築されたWebシステムのHTTPでの呼び出しインターフェースのこと。

RESTとは？
REpresentational State Transferの略で、分散型システムにおける複数のソフトウェアを連携させるのに適した設計原則の集合、考え方のこと。
RESTの原則に従うことでURIに規律が生まれ、サービス開発者が楽になるなどのメリットが生まれる！
※他に色々ありそうですが、今日のところは割愛させていただきます。

Swaggerの記述に方法については、YAML形式とJSON形式の2通り存在する。
(今回は、YAML形式で作成)

get,post,put,deleteメソッドについてそれぞれ1種類ずつ作成して見た。
AWSのAPIGateWayとも組み合わせることができるらしく、AWS上で構築したアプリケーション機能について、定義内容と一緒にすぐにAPIが試せるドキュメントが生成できるのは素晴らしい！！
海外では、API使用書をSwaggerで書くことがデファクトスタンダートとなっているらしい。。(自社でも取り入れたい！)

中身の基本的な構造については、下記の通りREADME.mdに記載されているため、参照いただきたい。

github.com

システム開発でも労力がかかり馬鹿にできないのがドキュメント作成作業。。。。
もしAPIもせっせとwordやらパワポやらで作成するとなると大変な労力となる。。

Swaggerについては、まだまだ勉強が必要であるが、その素晴らしさを垣間見ることができた！

【参考サイト】