プログラマの思索

Swaggerを使うと、WebAPIドキュメントをExcel仕様書から脱却してシステム化することができる。
自分はまだ無知なので、以下は自分用のメモのリンク。

【参考1】
【連載】Swagger入門 - 初めてのAPI仕様管理講座 [1] Swaggerとは｜開発ソフトウェア｜IT製品の事例・解説記事

(引用開始)
システム開発のトレンドとして、マイクロサービス化が進んできています。モノリス(一枚岩)スタイルの開発に比べて、アプリケーションの単位は小さくなり、多くのサービスが構築されます。

Uberの配車ビジネスやAirbnbの民泊に代表されるデジタルビジネスにおいても、APIエコノミー化が進んできており、Google Map APIやTwitter APIなどさまざまなAPIを組み合わせて素早くシステムを構築します。
Programmable Webでは、2017年1月時点で16,590以上のAPIが検索可能で、2009年9月の10倍以上、2006年5月の90倍近くに達しています。

では、そういったマイクロサービス・APIエコノミーの開発現場では、一体どのようなことが起こっているのでしょうか。

例えば、Androidのアプリから叩いているサーバのAPIが機能追加されたために、3日間かけてテストして終わったと思ったら、いつのまにか更なる仕様変更が入っていた。APIのインタフェースを定義するドキュメントの仕様に従ってアクセスしたら、実は実装との乖離があり、うまく動かなかった。

このようにAPIプロバイダとAPIコンシューマ間の悩みはさまざまです。ただし、いずれもサービスインに影響を及ぼす重大な問題と言えます。インタフェースの向こうの世界は関与できないことが多いだけに、仕様と実装の乖離はあってはならないものなのです。
APIエコノミーを作るにあたり、このようなことを起こさないためにも、APIについて正しく記述した仕様書が必要となってきます。
(引用終了)

【参考2】
Swaggerとは何か？ - プログラマでありたい

Swaggerを使ってインタラクティブなWeb APIドキュメントをつくる - Qiita

SwaggerでRESTful APIの管理を楽にする - Qiita

Swaggerの概要をまとめてみた。 - Qiita

【Swaggerの実例】
API リファレンス | SORACOM Developers

【1】Webシステムをモノリック・アーキテクチャからマイクロサービス・アーキテクチャで設計することで、まるで部品を組み立てるかのように、迅速にシステムを構築することが可能になった。
つまり、斬新なアイデアを実現するWebサービスを素早くリリースして、市場のニッチリーダーからシェア独占を狙って、先行者利益という独占利潤を得たいわけだ。

例えば、Uberの配車ビジネスやAirbnbの民泊。
日本なら、例えば、メルカリ、DMMとか。

現代は、これらシリコンバレー発祥のWebサービスが、自動車業界やホテル業界を直撃している、と言える。
よって、マイクロサービス・アーキテクチャで作られたWebサービスは、ありとあらゆる業界のビジネスモデルを一瞬にして破壊してしまう可能性が高い。
だから、こういうAPIエコノミーに対し、古い業界の人達も戦わざるを得ない。

【2】しかし、マイクロサービス・アーキテクチャの根幹となるWebAPIは、VerUpによってコロコロ変わってしまう問題がある。
そこで、I/F仕様をWebで公開して、即時に情報共有できるようにしたい。

つまり、マイクロサービス・アーキテクチャの実装基盤であるREST APIのI/F仕様を公開できるようなWeb基盤が欲しいわけだ。

【3】そこで、その候補として、Swaggerがあがる。
Swaggerの特徴は、「インタラクティブなWeb APIドキュメント」。

つまり、単純にWebへ公開できるドキュメントが作成できるだけでなく、リクエストを入力すればレスポンスを表示できる仕組みまである。
すなわち、APIをWebに公開できるだけでなく、使用しているAPIがVerUpしても使えるかどうか、事前に自動テストすることも可能。
これによって、Webサービスをリリースする時、利用しているAPIが使えなくなった、というリスクを減らすことができる。

たとえば、ソラコムさんのWebサイトが最も良い事例だろう。

API リファレンス | SORACOM Developers

上記の記事にもあるが、Dockerによるビルド環境構築やCIツールをSwaggerと組み合わせれば、マイクロサービスで組み立てたWebサービスの自動テスト、デプロイやリリース作業の自動化にもつながるだろう。
つまり、マイクロサービスで作られたWebサービスの品質向上、開発速度の向上にも役立てられるはず。

但し、Swaggerで全ての問題が解決されるわけではなく、まだ課題もある。
たとえば、Swaggerて゛のapi開発よもやま話の18ページにあるように、たくさんのAPIを一瞥できるような『オブジェクト構造図（仕様書のObjectの参照関係を階層構造で定義）』が欲しくなる。

【4】今の僕は、Excel仕様書からいかに脱却するか、というテーマを持っているが、その中でも、I/F仕様書は色んな意味で重要性が高い。

なぜなら、公開したI/Fというものは、自分のチーム以外の他チームも参照するので、説明責任が発生するし、I/Fの仕様はシステムのVerUpによって変わってしまう時が多いのに、その変更内容をExcelドキュメントへ反映する手間が結構かかるからだ。
しかも、I/FがVerUpで変わった、という事実を他チームにも随時連絡する手間も発生する。

よって、I/Fが変わったら、自チームがプッシュ通知するのではなく、他チームがプル通知で自動検知する仕組みの方が運用が楽になる。
そこで、SwaggerのようなWebAPIドキュメントの基盤を有効に活用できるだろう、と思う。

【4-1】ここで、I/F仕様書がSwaggerで置き換えられる可能性を考えると、現代という時代は、Excelドキュメントを一生懸命に書くよりも、仕様書というモノさえプログラミングする時代なのだ、という気がしてくる。

実際、単体・結合テストなどのテスト工程の作業は、TDDやCIなどの開発支援ツールでプログラミング作業に集約できる。
また、デプロイやリリース作業、そしてビルド環境や本番環境のインフラ構築作業も、DockerやGitHub、CIツール、AWSなどのクラウド環境などの技術によって、プログラミング作業で代替できるようになった。

今後は、要件定義や設計作業ではExcelドキュメントを書く、という作業も、きっとプログラミング作業で代替されるようになるだろう。
つまり、いちいち自然言語で要件や仕様を書くよりも、YAMLやJSONに似たデータ構造あるいはDSLによって、いきなりプログラムを書いた方が速いし、その後の保守更新も楽になる、という方向へ進化していくはずだ。

仕様書をプログラミング作業の本体であるテキストで代替できれば、Gitで管理できるし、そうすれば、TDD・CI・プルリクエスト・継続的デプロイなど昨今の開発支援技術の恩恵を受けられる。
よって、ドキュメントの情報共有が促進され、フィードバックを受けて修正すれば、仕様書の品質そのものも向上できるはず。

では、仕様書のExcel脱却の起点となる課題は何か？
答えは、Gitで管理できるか、そして、テキストからAPI仕様書や図表などを自動生成できるか、という課題に集約されるだろう、と思う。
幸いなことに、MarkdownやPlantUMLなどの記法でテキスト化すれば、HTMLやOfficeドキュメント、PDFへ自動生成するツール（Pandoc、MkDoc、他たくさん）で、今まさにたくさんの技術が実験されている。

この辺りの技術も、技術の進化の歴史の観点で今後整理していきたい。