Spring REST Docsの紹介

こんにちは、村上です。

今回は、私が最近プロジェクトで使用している Spring REST Docs [1]という Java のライブラリを紹介します。
Spring REST Docsを使うと Spring MVC Test で自動生成したスニペットと手書きのドキュメントを組み合わせ RESTfulなサービスのドキュメントを作成できます。

Spring REST Docs で出来ること

Spring REST Docsを使うと次のようなことができます。

  • Spring MVC Test を実行した結果をスニペット(Asciidoc)として出力できます。テストが失敗した時はスニペットは生成されません。
  • 自分で手書きしたドキュメント(Asciidoc)とスニペットを組み合わせられます。

基本は以上です。シンプルです。シンプルですが、Spring MVC Test を実行した結果から生成されるスニペットを利用するので、ソースコードに対する正しい仕様のドキュメントを作成できます[2]。ドキュメントが置いてけぼり….なんてのはよく聞く話です。Spring REST Docs を使えばテストが成功した時だけドキュメントが生成されるので、ドキュメントだけ置いてけぼりというを防げます。

Spring REST Docs のスニペットはAsciidocのファイルとして出力されます。なので、生成された後はAsciidoctorなどのツールをつかってHTMLやPDFなど好みのフォーマットに変換できます。

スニペット

Spring MVC Test を実行した結果から標準で生成できるスニペットには次のようなものがあります。

  • テスト実行時と同じリクエストを送信するcurlコマンド
  • テスト実行時HTTPリクスト、HTTPレスポンス
  • リクエスト、レスポンスのペイロードのドキュメント(JSON, XMLをサポートしています)

Spring REST Docsは標準のスニペットの生成に Mustache のテンプレートを使っていて、カスタムのテンプレートを指定することで標準のスニペットの出力をカスタマイズすることもできます。
さらにスニペットの生成は Snippet インタフェースを実装すれば任意のスニペットを出力することもできます。

まとめ

今回は、Spring REST Docs というライブラリとそれで何ができるか、できそうかを紹介しました。
次回は、Spring REST Docs を使って実際にスニペットを出力するまでを紹介したいと思います。

  1. このブログ記事を書いている時点では 1.0.0.RC1が最新ですが、まもなく1.0.0.RELEASEがリリースされそうな状況です。次回の記事が公開される頃には1.0.0.RELEASEがリリースされているかもしれません。
  2. REST APIのドキュメントを生成できる Swagger もあります。Swagger は REST API の仕様をYamlで表現し、様々なツールでそれを利用するツールです。ドキュメントだけでなく、ソースコードを生成したりもできます。Spring REST Docsはテストを通して正しいドキュメントを作成することに焦点を当てている点が Swagger とは違います。