Swaggerを使った開発アプローチ
はじめに
Swaggerを使ったAPI開発は、業務でも個人開発でもお世話になることが多いのですが、具体的な『開発手法』や『開発アプローチ』について考えたことがなかったので、調べてみました。
2つの開発手法
Swagger 公式Blogや、個人Blogの中には、開発手法に関して言及しているものがいくつか存在します。 それらの中では主に2つの開発手法が示されています。
Design First or Code First: What’s the Best Approach to API Development? より引用
- デザインファースト(トップダウン型)
- コードファースト(ボトムアップ型)
の2つが紹介されています。
これら2つのアプローチについて、『どういったものなのか？』『どういった場合に使用が勧められるのか？』ということを次の項から見ていきます。
デザインファースト(トップダウン型)
『OpenAPIの仕様(swagger.yamlなど)から、コードを生成する。』手法を指します。
与えられた要件から、コードの元となるSwaggerドキュメントの設計を行います。Swaggerドキュメントの設計が完了した時点で、それを元にコードを自動生成していくといった形をとります。
適用が勧められるケースとして、下記のようなケースが紹介されています。
①外部ユーザーに対して重要度の高いAPIを公開する場合
外部ユーザーに対して、重要度の高いAPIを公開する場合は、APIの仕様が非常に重要になります。外部ユーザーはAPIの内部構造を覗き見ることができないため、仕様に関するドキュメントが全てとなります。 特に境界面となるインタフェースプロパティ、パス、パラメータは非常に重要なため、予め明文化されたSwaggerドキュメントなどからコードを自動生成する方が、情報の一貫性を保つことができます。
②チーム間での開発コミュニケーションを重要視する場合
開発の分化が進んでいるチームでは、バックエンドとフロントエンドが分かれていることが、ほとんどだと思います。
この場合、1チームや1人の開発者がフロントエンドとバックエンドを一緒に作るわけではないため、APIに関する情報を各チームに対して共有しておく必要があります。
情報共有を『コードを見て判断してください。』や『Excelドキュメントを参照してください。』のようにフォーマットの定まっていない形式で行ってしまうと、情報共有にかかる時間を無駄に費やしてしまうことになります。
Swaggerドキュメントで既定のフォーマットを使用すれば、円滑な情報共有を促すことができます。
フロントエンドはSwaggerドキュメントからエンドポイントの情報や認証情報、型に関する情報を得ることができます。Swaggerドキュメントから簡易的なMockサーバーを生成することもできます。
バックエンドは、そのままAPIを自動生成し、内部の処理を実装するだけで済みます。
コードファースト(ボトムアップ型)
『コードから、OpenAPIの仕様を生成する。』手法を指します。 与えられた要件から、コーディングを開始して機能が完成したところで、コードからSwaggerドキュメントを自動生成していくといった形をとります。
適用が勧められるケースとして、下記のようなケースが紹介されています。
①素早く製品をリリースしたい場合
デザインファーストでは、インターフェースに関わる部分のコード生成を自動化することはできますが、重要な『処理』に関する部分のコードは自動生成できません。
DBからデータを取得する処理や、パラメータに対して何らかの操作を行う処理もすべて自前で記述する必要があります。
そのため、スピードが重視される場面において、ドキュメント生成をしてから、インターフェース部分のコードを自動生成して、インタフェースを崩さないように処理部分を実装する。というプロセスはあまり好ましくありません。
加えて、デザインファーストはあくまでドキュメントから自動生成されたコード群に過ぎないため、運用を考慮したフォルダ構成やアーキテクトになっているわけではありません。
CI/CDによる素早いリリースプロセスを実行していくためには、Toolによる自動化が欠かせませんが、運用を考慮しないフォルダ構成やアーキテクトでは、この自動化が非常に困難になります。
こういった場合は、コードファーストで先に開発を行い、コードからSwaggerドキュメントを自動生成してしまう方が良いとされています。
②PrivateなAPIを開発する場合
外部公開を目的としないAPIや、企業内部で限定的な利用しかしないAPIを作成する場合は、コードファースト型の開発が適しているとされています。 これは、公開APIの開発と比較して、内部限定のAPI開発はインタフェースの規約が緩いことが多いため、仕様に関するドキュメントの重要性がそこまで高くない。というのが理由のようです。
まとめ
- OpenAPIの仕様から、コードを生成する『デザインファースト(トップダウン型) 』
- コードから、OpenAPIの仕様を生成する『コードファースト(ボトムアップ型)』
- どちらが良いではなく、実際の開発に求められる要件に基づいて手法を選択する。
