Swagger（Open API Specification）をベースにして生成されるデータ、コードについて

Swaggerフォーマット（Open API Specification）でAPIドキュメントを作成するとどんなメリットがあるのか紹介します。一つのフォーマットから多彩な展開ができるようになっていると、開発工数を低減や品質向上に大きく寄与するはずです。

ドキュメント

Swaggerを使ってドキュメントを生成するのは基本と言えます。多くの方がSwaggerをAPIドキュメントのために使っているのではないでしょうか。Swagger UIのようなツールを使うと、その場でAPIをコールできる機能が付いたドキュメントが生成できます。

現状の問題はあまりフレキシブルな機能をもったドキュメント生成ツールが多くないことでしょう。Swagger UIにもテーマはありますが、まだあまり多くありません。そのため、Swagger UI製のドキュメントはどれも似た雰囲気になってしまっています。

コード

Swagger UIを使ったコード生成ツールとしてSwagger Editorが挙げられます。クライアント/サーバサイドのコードを生成可能で、多くのプログラミング言語に対応しています。自動生成なので使い勝手がとても良いコードではないこともありますが、それをベースにラッピングして使いやすいSDKに仕上げることもできるでしょう。

さらにかつてのWSDLのようにスケルトンコードの生成機能をもったライブラリもあります。そうしたツールを使うことで、APIファーストであったりAPIの追加に伴うライブラリメンテナンスコストの削減が実現できるようになります。

モックサーバ

SwaggerのベースであるJSON/YAMLファイルはサーバの動作を規定したファイルになります。そこで開発用のモックアップサーバとして使えるソフトウェアがあります。あくまでもモックではありますが、クライアントアプリケーションの開発に役立ちます。

サーバとクライアントサイドの開発が分かれている場合、APIが整っていない状態ではクライアント側の開発が行えずに遅延してしまうことが多々あります。ドキュメントを先に整備することでクライアント側の開発がスムーズになるでしょう。

バリデーション

JSON SchemaのようにSwaggerを使ってバリデーションを行うことが可能です。バリデーションは複数パターン考えられます。

クライアントサイドのリクエスト検証

クライアントサイドでデータを送信する前に検証します。これによりUXを向上させたり、サーバ側のアクセスを減らすことができます。さらにJavaScriptによるバリデーションのコードを書かなくて良くなるのでコードの重複、メンテナンスコストを軽減できます。

サーバサイドのリクエスト検証

クライアント側と同様にサーバ側も送られてきたデータの検証ができるようになります。これが大多数の目的になるでしょう。サーバ側でも入力値の検証を行うのは面倒なので、Swagger内で定義されている内容を元に検証できると手軽です。

クライアントサイドのレスポンス検証

さらにクライアントサイドではサーバから送られてきたレスポンスについて検証を行うこともできます。多くの場合、サーバレスポンスは無条件に信用してしまいがちですが、データが欠損してたり仕様と異なることはよくあります。

テストケース

Swaggerを使ったテストとしてはAPIサーバの実装が正しく行われているかどうかの検証が大きな目的になるでしょう。これはドキュメント/テストファーストで実装した時に役立ちます。また、定期的に実行することで実装が変わっていないことの検証も可能です。

テストケースを生成するソフトウェアの場合、多くは正常系のテストになるようです。そのため、異常系のテストを行う際には多少のメンテナンスが必要になるので注意してください。

Swaggerのドキュメントを整備することで多くの利用が可能になります。APIドキュメントファーストとも言える駆動型開発で効率的な開発を行ってください。