はじめまして、ソリューションSecの井上です。

突然ですが、皆さんはAPIの仕様書ってどの様に作成されていますか？
私が見てきた現場では断然Excelで作成する事が多く、
実際Excelで作成される方がほとんどなのではないでしょうか。
ただ、Excelはただの方眼紙上に記載していくだけの機能しかありません。
逆にシンプルだからこその強みが様々な用途で使われている理由なんだと思いますが笑

そこで以前機会があり使用して便利だなと感じた Swagger をサクッとご紹介したいと思います。

そもそもSwaggerとは？

端的に言うとSwaggerは海外の有志の方により立ち上げられた、
RESTfulAPIを楽に設計、製造しよう！という為のプロジェクトとそのツール郡です。
マイクロソフト、グーグル、IBMらが発足したOpenAPI Initiativという
RESTfulAPIのフォーマットを標準化しよう、という団体でSwaggerが採用されるなど
海外ではかなり主流となっております。

じゃあSwaggerって何が出来るの？

Swagger Specという仕様を元にドキュメントを記載しておけば、
自動で見やすいドキュメントやコードの生成などが行えます。
主に Editor、UI、Codegen の３つのツールがメインになっています。
それぞれの軽い説明をしたいと思います。

Swagger Editor

Swagger Specを記載する際のエディタです。
ここ(公式webエディタ)を開いてみて貰えばわかるかもしれないですが、
YAMLやJSONなどの形式でAPI仕様を記載出来るエディタです。
右側に実際にドキュメントを生成した際の見た目を確認しながら記載できるので非常に便利です。
webブラウザ上だけでなくDockerなどで環境を構築すればローカルでの実行も出来ます。

Swagger UI

先程開いてもらった公式webエディタの右半分に出ていた様なドキュメントを出力出来るツールです。
エンドポイントやパラメータなど、どう送れば何がどう返ってくるのかなどが非常に詳しくわかる様になっています。
定義を更新した後に再生成するだけで最新の状態になる為、
煩わしい更新作業やバージョン管理が不要になります！

Swagger Codegen

Swaggerで記載したAPI仕様からコードを生成しAPIのスタブを作成してくれます。
なので後は内部の処理を追加していくだけ、という感じです。
多くの言語に対応しているのでさまざまな案件にも対応できます！
こちらのgithubのリポジトリに説明や使い方などが記載されています。

まとめ

本当であればもっと細かい部分についても触れていきたいところではありますが、
こんな便利なものもあるんだな、へ～。ぐらいにでも思ってもらえたら幸いです。
導入しようと思うと時間が掛かったりや覚えなければいけない事なども出てきますが、
使いこなせる様になるととても便利なツールです。
興味を持って頂けた方がチャレンジするきっかけにでもなれたらいいなと思います。