Spring REST Docs のデザインをお手軽にオシャンティーにする

おはようございます、BE 側の JK です

Spring で REST API を設計した際にドキュメント化する方法として Spring REST Docs があるのをみなさんご存知でしょうか

公式のサンプルがいくつかあるので試しに見てみましょう

今回は唯一 Maven を使用したサンプルである "Spring Data REST" プロジェクトを使います（他は Gradle でしたねー）

git clone https://github.com/spring-projects/spring-restdocs.git
cd spring-restdocs/samples/rest-notes-spring-data-res
./mvnw package

ビルド後に target/generated-docs に HTML が生成されます

Spring REST Docs ではテストコードで実行した API の結果や説明が自動的に HTML に組み込まれますが、その結果は api-guide.html で確認できます、開いてみましょう

open target/generated-docs/api-guide.html

いい感じですねー

ドキュメントの大元は src/main/asciidoc に AsciiDoc 形式で書かれています

HTML へのパースは Asciidoctor が使用されています

もうちょいオシャンティーにしたいなー

AsciiDoctor は CSS や JS を組み込んでテーマを作成することができます

テーマを作る時間はない！手軽に綺麗な見た目にしたい。。。。。

うーん

そういえば、Spring のドキュメントサイトは見やすいデザインになっていますね

このテーマ、どこかで公開されているのでは。。。

されていました

早速使ってみましょう！

うーん

少し手順が多いですね、またそのままコピーしてもうまく動かないため色々変更する必要があります....

やはり、手軽にオシャンティーにする方法はないのか。。。。。。

うん？

魔法のリポジトリがありました、どうやら3月に出たばっかりです

導入も簡単そうです

では導入してみましょう

変更点は下記のコミットを参照してください

再ビルドします

./mvnw clean package

ドキュメントをリロードすると。。。。。

オシャンティーになってますねー

右上のトグルをクリックすることでダークテーマにも変えられます、素晴らしいですね

CSS を上書きすることで左上のロゴを変えることもできます