Spring REST Docs

手書きのドキュメントと、Spring MVC テストまたは WebTestClient で生成された自動生成スニペットを組み合わせて、RESTful サービスをドキュメント化します。

Spring REST Docs の目的は、RESTful サービスに関する正確で読みやすいドキュメントを作成できるようにすることです。

高品質のドキュメントを書くことは困難です。その難しさを軽減する 1 つの方法は、ジョブに適したツールを使用することです。このため、Spring REST Docs はデフォルトで Asciidoctor (英語) を使用します。Asciidoctor は、プレーンテキストを処理し、ニーズに合わせてスタイルとレイアウトが設定された HTML を生成します。必要に応じて、Markdown を使用するように Spring REST Docs を構成することもできます。

Spring REST Docs は、Spring MVC のテストフレームワークまたは Spring、WebFlux の WebTestClient で記述されたテストによって生成されたスニペットを使用します。このテスト駆動型のアプローチは、サービスのドキュメントの正確性を保証できます。スニペットに誤りがある場合、それを生成したテストは失敗します。

RESTful サービスをドキュメント化することは、主にそのリソースを説明することです。各リソースの説明の 2 つの重要な部分は、それが消費する HTTP リクエストの詳細と、それが生成する HTTP レスポンスです。Spring REST Docs を使用すると、これらのリソースと HTTP リクエストおよびレスポンスを操作して、サービスの実装の詳細からドキュメントを保護できます。この分離は、サービスの実装ではなく、サービスの API をドキュメント化できます。また、ドキュメントを作り直すことなく実装を進化させることができます。