SpringOneの中からDocumentingのセッションをpickupし、Spring REST Docsの導入方法 Spring REST Docsを利用し、 どのように鮮度の高いドキュメントが作成できるか どのようなメリットがあるか について説明しています。 1.Title 2.Introduction 3.Agenda 4.Title 5.Title 6.良いドキュメンテーションの仕組みとは何か 7-9.Springを利用しているアプリではどのような仕組みがあるか(Swagger) 10.良いドキュメンテーションの仕組みとは何か(2) 11-15.Springに適したドキュメンテーションの仕組み 16-20.Spring REST Docs 21-32.どのようにSpring REST Docsを動かすか 33-37.AsciiDoctorとは何か 38-46.AsciiDoctorの親ドキュメントの作成について 47-49.ドキュメントをjarに内包する 50-51.おさらい 52-53.Spring REST Docsを使うことのメリットについて 54.Spring REST Docsを使ってみて考えたこと 55-57.Appendix 58.Spring REST Docs 1.0.1 59.END

1. SpringOneを経験してよりよいWebサービスを作るために僕らが取り組むこと
Takahiro Fujii
Thomas Ludwig
1

2. Introduction
2
Takahiro Fujii(@taka_ft)
Team Maneger
Booking Front Team
Travel Platform Group
Travel Service Development Department

3. Agenda
3
https://jsug.doorkeeper.jp/events/34341

4. Spring REST Docsを利用して鮮度の高いDocumentを運用しよう
Takahiro Fujii
4

5. Topic
Documentation
5

6. 良いドキュメンテーションの仕組み
・良いドキュメンテーションの仕組みとはなにか
・簡単にドキュメントが作れる
・見やすいドキュメントを作成することができる
・ドキュメントを更新するコストが低い
・嘘をつかない（ドキュメントと実装の差分が発生しにくい）
6

7. 良いドキュメンテーションの仕組み
Springを利用している
アプリケーションではどうか？
7

8. Swagger
8
http://swagger.io/

9. Swaggerの考慮すべき点
・URI baseのドキュメンテーション
・Documentationのためのコードがロジック側にはいる
・DRYではない
(重複したコードをエンドポイント毎に定義する必要がある)
・Test-Driven Documentationしづらい
・Hypermediaをサポートしていない
・ライブラリのサイズ大きい(約31MB)
※Swaggerは良いツールです
※Sessionの動画でより具体的な点に触れています
9

10. 良いドキュメンテーションの仕組み
・良いドキュメンテーションの仕組みとはなにか
・見やすいデザインが作りやすい
formatを使ってドキュメントを書くことができる
・ドキュメントを作成するために(ロジック側に)実装を必要としない
・ドキュメントが正確だと保証することができる
10

11. 良いドキュメンテーションの仕組み
Springに適した
ドキュメンテーションツール
11

12. 良いドキュメンテーションの仕組み
12
http://asciidoctor.org/

13. 良いドキュメンテーションの仕組み
13
http://docs.spring.io/spring-framework/docs/4.2.x/spring-framework-reference/htmlsingle/#spring-mvc-test-framework

14. 良いドキュメンテーションの仕組み
Springに適した
ドキュメンテーションツール
14

15. 良いドキュメンテーションの仕組み
がAsciiDoctorとSpring MVC Test
を軸に作られました。
15

16. Spring REST Docs
16
http://projects.spring.io/spring-restdocs/

17. 2015/10/07にでたばっかり！
17
https://github.com/spring-projects/spring-restdocs/releases

18. こんなものがつくれます(html)
18

19. こんなものがつくれます(自動生成してくれます）
19

20. SpringOne’s session
Spring REST DocsはどのようにREST APIのドキュメ
ンテーションを助けてくれるのか
DOCUMENTING RESTFUL APIS
https://2015.event.springone2gx.com/schedule/sessions/documenting_restful_apis.html
Slide
http://www.slideshare.net/SpringCentral/documenting-restful-apis
20

21. どのようにSpring REST Docsを使うか、
残りの時間でできる限り話します。
21

22. Spring REST Docs使ってみましょう
Springのサンプル REST apiを
Spring REST Docsを使って、
ドキュメンテーションを作成し
てみます。
※スライドを読み返してくれ
ている方は、右のリンクから
サンプルapiをチェックアウト
して、実際にコードを書きな
がら試してみることをお勧め
します。
22
https://spring.io/guides/gs/rest-service/

23. イメージ
src/test/javaの下に
*Documentation.javaというクラス
を作成します。
23
spring mvc testのテストコードに、
documentするためのmethodを追
加するようなイメージ

24. dependency/build設定の追加
24
http://docs.spring.io/spring-restdocs/docs/1.0.0.RELEASE/reference/html5/#getting-started-build-configuration-gradle
http://docs.spring.io/spring-restdocs/docs/1.0.0.RELEASE/reference/html5/#getting-started-build-configuration-maven
まずは公式ドキュメントに書いてある設定を使ってみてください。
各項目で何をしているかの説明も記載されています。

25. dependency/build設定の追加(1)
25
http://docs.spring.io/spring-restdocs/docs/1.0.0.RELEASE/reference/html5/#getting-started-build-configuration-gradle
http://docs.spring.io/spring-restdocs/docs/1.0.0.RELEASE/reference/html5/#getting-started-build-configuration-maven
Dependencyとして追加するのはこれだけ
(そのうちstarterに入りそうな気もします)

26. dependency/build設定の追加(2)
26
http://docs.spring.io/spring-restdocs/docs/1.0.0.RELEASE/reference/html5/#getting-started-build-configuration-gradle
http://docs.spring.io/spring-restdocs/docs/1.0.0.RELEASE/reference/html5/#getting-started-build-configuration-maven
*Documentation.javaをunit testの実行対象にします

27. dependency/build設定の追加(3)
27
http://docs.spring.io/spring-restdocs/docs/1.0.0.RELEASE/reference/html5/#getting-started-build-configuration-gradle
http://docs.spring.io/spring-restdocs/docs/1.0.0.RELEASE/reference/html5/#getting-started-build-configuration-maven
ドキュメント(.adoc形式)をhtmlに変換するために必要です(他の形式にも変更可能)（後述します)
※公式ドキュメントではpropertiesで
この値をsnippetsDirectoryで定義しています

28. dependency/build設定の追加(4)
28
http://docs.spring.io/spring-restdocs/docs/1.0.0.RELEASE/reference/html5/#getting-started-build-configuration-gradle
http://docs.spring.io/spring-restdocs/docs/1.0.0.RELEASE/reference/html5/#getting-started-build-configuration-maven
生成されたdocumentをjarの中に内包したい場合必要（後述します)

29. static importが多いので
29
IDEでsuggestされるようにしておく(※上の図不完全)

30. さぁ、実装してみましょう
30
GreetingDocumentation.javaを実装してみましょう

31. 前処理
31
MockMvcのinstanceを作るときに、Documentationのoutputを指定

32. Actual code(Sample)
32
Build
この3つの.adocファイルがビルド時に生成される(デフォルト)
※ここを変更するとdocumentが
できるディレクトリを分けられます

33. adocって？
.adocって何？
33

34. adocって？
http://asciidoctor.org/docs/what-is-asciidoc/
34

35. adocって？
・.adocはasciidoctorの拡張子
・Markdownのようなマークアップ言語
・HTMLやPDFなどに変換してくれる機能を有している
35

36. adocって？
36
[source,bash]
----
$ curl 'http://localhost:8080/greeting?name=takahiro' –I
----
[source,http]
----
GET /greeting?name=takahiro HTTP/1.1Host: localhost
----
[source,http]
----
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 37
{"id":1,"content":"Hello, takahiro!”}
----
curl-request.adoc
http-request.adoc
http-response.adoc
adocを直接開くとこんな感じです。

37. adocって？(対応
37
curl-request.adoc
http-request.adoc
http-response.adoc
add-on,plugin
firefox : https://addons.mozilla.org/ja/firefox/addon/asciidoctorjs-live-preview/
chrome : https://chrome.google.com/webstore/detail/asciidoctorjs-live-
previe/iaalpfgpbocpdfblpnhhgllgbdbchmia
sublime : https://github.com/asciidoctor/sublimetext-asciidoc
atom : https://github.com/asciidoctor/atom-asciidoc-preview
対応しているブラウザ/ソフト
で開くとこんな感じに表示されます。

38. で、これをどうすれば？
38

39. Spring REST Docsって何してくれるの？
39
http://projects.spring.io/spring-restdocs/
snippet : 切れ端・断片

40. SpringRESTDocsは
snippets(断片)
を自動生成してくれるもの
40

41. snippetsの親は自分で用意
41

42. 親adoc
42
src/main/asciidocの下に
*.adocというファイルを作成します。
api-guide.adocの中で、
SpringRESTDocsで生成したsnippets
をincludeすることができます。

43. 親adocは、公式ドキュメントにのっている
sample projectのapi-guide.adocを参考にして
作ってみるのがいいかと思います。
43
https://raw.githubusercontent.com/spring-projects/spring-restdocs/v1.0.0.RELEASE/samples/rest-notes-spring-hateoas/src/docs/asciidoc/api-guide.adoc
https://raw.githubusercontent.com/spring-projects/spring-restdocs/v1.0.0.RELEASE/samples/rest-notes-spring-data-rest/src/main/asciidoc/api-guide.adoc

44. 親adocがある状態でもう一度buildしてみると、、
動きます
44

45. ついにhtmlが
45
指定した形式に変換されたapi-guide.*が作成されます。
pom.xml

46. もちろん開くことができます。
46

47. もう一つ
47

48. jarに内包させることが可能です。(アプリの中に入れる)
48

49. jarに内包させることが可能です。
49
pom.xml

50. Spring MVC Test
おさらい
50
1.SpringRESTDocsが部品(snippets)を作ってくれる(with SpringMVCTest)
2. snippetsをincludeする.adocファイルを作ると、ビルド時に
指定した形式に変換してくれる
SpringRESTDocs
*-request.adoc
*-response.adoc
*Documentation.java
api-guide.adoc
*-request.adoc
*-response.adoc
Asciidoctor
api-guide.html
snippets

51. targetフォルダ
おさらい
51
targetの中にできるので、
例えばJenkinsとかのbuild
からドキュメントが参照できる
api-guide.html
appname.jar
api-guide.html
アプリの中にドキュメントを組み込み、
アプリ配下にドキュメントページ
を組み込める

52. SpringRESTDocsの何がいいのか
52
・(望むなら)testと一緒にdocumentが生成される
・testが通ったらdocumentがつくられるという仕組みを提供
・正しくないdocumentが限りなく作りにくい
・Wikiにありがちな、更新されないdocumentを作らせない
・Test Driven Documentation
・(一度使い方を理解すれば)新規のアプリで動かすのが楽
※最初はmockでapiを作っておいてドキュメントを先に用意して提供することも可能
テスト
成功
Create document
start
end
false
true

53. Testからドキュメントを作ることのメリット
53
この結果はtest codeの中で実際にapiをcallして返ってきた値から作られている。
つまり仕様が変わればDocumentは変わる。
(HelloからGood mornningに変えれば生成されるドキュメントも変わる)
Endpointを変えてテストが失敗されればエラーがでてDocumentは生成されない
※もちろんMVC Testでもっと厳密な試験も可能

54. かんがえること
・Test CodeとしてのDocumentation.javaの位置付け
(*Documentation.javaに書くテストは何のテストなのか)
Document how to separate REST documenting tests from 'real' Junit tests
https://github.com/spring-projects/spring-restdocs/issues/89
・このドキュメンテーションの位置付け
（SpringRESTDocsでつくられるドキュメントは誰のためのドキュメント？)
（例えばこのドキュメンテーションを外部に出せる状態で常に維持するのか
エンジニアのためのものか）
54

55. Appendix(Support Hypermedia format)
55
Spring sample project : https://spring.io/guides/gs/rest-hateoas/

56. Appendix(Parameter Description)
56
requestParameters/requestFields/responseFields

57. Appendix(Customize template)
57
Reference : http://docs.spring.io/spring-restdocs/docs/1.0.0.RELEASE/reference/html5/#documenting-your-api-customizing-snippets

58. 1.0.1 coming soon.
58
Reference : https://github.com/spring-projects/spring-restdocs/milestones
1.0.1 がもうすぐでそうです : )

59. Thank you !
59