こまぶろ

技術のこととか仕事のこととか。

Web API の仕様をOpenAPI Specで書いてみて

以前、OpenAPI Generatorの紹介記事を書いた。

ky-yk-d.hatenablog.com

上の記事を書いてから、実際のプロジェクトでOpenAPI SpecでAPIの仕様を書くとともに、その定義ファイルからOpenAPI GeneratorでAngularのクライアントコードを自動生成するということを始めた。まだ課題もあるが、中間報告を書く。

前提条件

今回開発対象としているAPIサードパーティによる利用を想定したものではなく、もっぱら自社で開発するクライアント(Web/モバイル)から利用されるもの。サーバとクライアントを並行で開発しており、APIの仕様を決めるに当たってはクライアントでの利用のしやすさを重視している。

開発チームとしては、サーバでHTMLを生成する種類のWebアプリケーション開発の経験が長いメンバーが多く、Web API開発の知見はチーム内に乏しい。また、これまで仕様書はExcelがメインであったとともに、構成管理ツールとしてもVSS/TFSに慣れ親しんでいるメンバーがほとんどである。

やっていること

現在は、以下の事柄を実施している。

  • OpenAPI SpecによるAPI仕様の記述
  • 上記ファイル(YAML)のGitでの管理
  • ReDocによるHTMLドキュメントの生成
  • OpenAPI GeneratorによるAPIクライアントコードの生成

補足すると、YAMLファイル(およびそこから生成されたHTMLドキュメント)がAPI仕様の正式版ではあるものの、いきなりYAMLファイルを記述するのは辛いので、仕様を検討する過程では一度Excelに記述するようにしている。Excelのフォーマットは、自動生成したHTMLドキュメントの記載項目を参考に作成した。

OpenAPI Generatorのスタブサーバのコード自動生成の機能は、開発の当初の段階では試してみたが、現在は使っていない。クライアントの開発がサーバの開発に先行している場面では、クライアントコードの中にダミーデータを直書きすることで済ませている。また、HTMLドキュメントの生成は、OpenAPI Generatorでも可能だが、見やすいものではなかったためReDocという別のツールを利用している。

github.com

iktakahiro.hatenablog.com

よかったこと:情報の集約

スキーマ駆動開発」というテーマの特集を読んで導入したOpenAPIだったが、ここまでのところで実感している効用はむしろ、「情報の集約」という側面に関するものである。

具体的には、チーム内で(あまりよくないことだが)よく交わされる「〇〇ってどの資料に書いてありましたっけ」という会話が、Web APIの仕様については全く発生しない。

自社はドキュメントをそれなりに作る会社なので、各種の設計書を作成する際に利用できる標準フォーマットがある程度整備されている。しかし、標準的なものがないケースにおいては、まず大雑把な資料が作成され、プロジェクトが進んで情報が増えていく中でより詳細な、あるいは別の側面からの資料が作成される。その結果、フォーマットの異なる複数のファイルに情報が散逸するということになりやすい。

Web APIの仕様についても、社内には標準がないので、当初は上のような管理が困難な状況に陥りそうになっていた。しかし、OpenAPI Specの導入により、YAMLファイルが単一の情報集約点となった。OpenAPI Specでは様々な情報を記述することができるようになっているから、原則としてYAMLファイルに情報が追加されるようになる。

YAMLファイルには記述しづらい情報のために、補足的な資料を作成することがあっても、YAMLファイルが主たる地位を占めることはチーム内で了解されているので、情報が散逸しづらいのだ。また、OpenAPI Specの仕様で「どのような情報を記述できるか」を知ることは、開発の経験が乏しいWeb APIについて「どのような事柄を考慮すべきか」を考える助けにもなっている。

展望と課題:その他の情報の集約と「スキーマ駆動」

「情報の集約」は、OpenAPIの導入に拠らずとも達成されうるものであるし、本来は達成されているべきものだ。抱えている問題のレベルの低いというのは一方で真理だろう。しかし、自分の現場にとっては、OpenAPIという仕様とその周辺ツール群が、その問題を浮き彫りにすると同時に、解決できるものであることを気づかせてくれた。この気づきを承けて、Web APIの定義以外のドキュメントも、なるべく一箇所に集めるように動き始めている。

一方で、先に述べた通り、スキーマという部分でのメリットはあまり享受できていない。また、各種ツールを利用することによるメリットも最大限享受できているとはいえない。あまり色々やろうとしすぎても大変&混乱を招くのでそこは注意したいが、ツールの導入を少しずつ進めていきたいなとは思っている。

WEB+DB PRESS Vol.108

WEB+DB PRESS Vol.108

  • 作者: 中野暁人,山本浩平,大和田純,曽根壮大,ZOZOTOWNリプレースチーム,権守健嗣,茨木暢仁,松井菜穂子,新多真琴,laiso,豊田啓介,藤原俊一郎,牧大輔,向井咲人,大島一将,上川慶,末永恭正,久保田祐史,星北斗,池田拓司,竹馬光太郎,粕谷大輔,WEB+DB PRESS編集部
  • 出版社/メーカー: 技術評論社
  • 発売日: 2018/12/22
  • メディア: 単行本
  • この商品を含むブログを見る