Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
SpringOneを経験してよりよいWebサービスを作るために僕らが取り組むこと
Takahiro Fujii
Thomas Ludwig
1
Introduction
2
Takahiro Fujii(@taka_ft)
Team Maneger
Booking Front Team
Travel Platform Group
Travel Service Development D...
Agenda
3
https://jsug.doorkeeper.jp/events/34341
Spring REST Docsを利用して鮮度の高いDocumentを運用しよう
Takahiro Fujii
4
Topic
Documentation
5
良いドキュメンテーションの仕組み
・良いドキュメンテーションの仕組みとはなにか
・簡単にドキュメントが作れる
・見やすいドキュメントを作成することができる
・ドキュメントを更新するコストが低い
・嘘をつかない(ドキュメントと実装の差分が発生しに...
良いドキュメンテーションの仕組み
Springを利用している
アプリケーションではどうか?
7
Swagger
8
http://swagger.io/
Swaggerの考慮すべき点
・URI baseのドキュメンテーション
・Documentationのためのコードがロジック側にはいる
・DRYではない
(重複したコードをエンドポイント毎に定義する必要がある)
・Test-Driven Doc...
良いドキュメンテーションの仕組み
・良いドキュメンテーションの仕組みとはなにか
・見やすいデザインが作りやすい
formatを使ってドキュメントを書くことができる
・ドキュメントを作成するために(ロジック側に)実装を必要としない
・ドキュメント...
良いドキュメンテーションの仕組み
Springに適した
ドキュメンテーションツール
11
良いドキュメンテーションの仕組み
12
http://asciidoctor.org/
良いドキュメンテーションの仕組み
13
http://docs.spring.io/spring-framework/docs/4.2.x/spring-framework-reference/htmlsingle/#spring-mvc-te...
良いドキュメンテーションの仕組み
Springに適した
ドキュメンテーションツール
14
良いドキュメンテーションの仕組み
がAsciiDoctorとSpring MVC Test
を軸に作られました。
15
Spring REST Docs
16
http://projects.spring.io/spring-restdocs/
2015/10/07にでたばっかり!
17
https://github.com/spring-projects/spring-restdocs/releases
こんなものがつくれます(html)
18
こんなものがつくれます(自動生成してくれます)
19
SpringOne’s session
Spring REST DocsはどのようにREST APIのドキュメ
ンテーションを助けてくれるのか
DOCUMENTING RESTFUL APIS
https://2015.event.spring...
どのようにSpring REST Docsを使うか、
残りの時間でできる限り話します。
21
Spring REST Docs使ってみましょう
Springのサンプル REST apiを
Spring REST Docsを使って、
ドキュメンテーションを作成し
てみます。
※スライドを読み返してくれ
ている方は、右のリンクから
サンプル...
イメージ
src/test/javaの下に
*Documentation.javaというクラス
を作成します。
23
spring mvc testのテストコードに、
documentするためのmethodを追
加するようなイメージ
dependency/build設定の追加
24
http://docs.spring.io/spring-restdocs/docs/1.0.0.RELEASE/reference/html5/#getting-started-build-c...
dependency/build設定の追加(1)
25
http://docs.spring.io/spring-restdocs/docs/1.0.0.RELEASE/reference/html5/#getting-started-buil...
dependency/build設定の追加(2)
26
http://docs.spring.io/spring-restdocs/docs/1.0.0.RELEASE/reference/html5/#getting-started-buil...
dependency/build設定の追加(3)
27
http://docs.spring.io/spring-restdocs/docs/1.0.0.RELEASE/reference/html5/#getting-started-buil...
dependency/build設定の追加(4)
28
http://docs.spring.io/spring-restdocs/docs/1.0.0.RELEASE/reference/html5/#getting-started-buil...
static importが多いので
29
IDEでsuggestされるようにしておく(※上の図不完全)
さぁ、実装してみましょう
30
GreetingDocumentation.javaを実装してみましょう
前処理
31
MockMvcのinstanceを作るときに、Documentationのoutputを指定
Actual code(Sample)
32
Build
この3つの.adocファイルがビルド時に生成される(デフォルト)
※ここを変更するとdocumentが
できるディレクトリを分けられます
adocって?
.adocって何?
33
adocって?
http://asciidoctor.org/docs/what-is-asciidoc/
34
adocって?
・.adocはasciidoctorの拡張子
・Markdownのようなマークアップ言語
・HTMLやPDFなどに変換してくれる機能を有している
35
adocって?
36
[source,bash]
----
$ curl 'http://localhost:8080/greeting?name=takahiro' –I
----
[source,http]
----
GET /greeti...
adocって?(対応
37
curl-request.adoc
http-request.adoc
http-response.adoc
add-on,plugin
firefox : https://addons.mozilla.org/ja...
で、これをどうすれば?
38
Spring REST Docsって何してくれるの?
39
http://projects.spring.io/spring-restdocs/
snippet : 切れ端・断片
SpringRESTDocsは
snippets(断片)
を自動生成してくれるもの
40
snippetsの親は自分で用意
41
親adoc
42
src/main/asciidocの下に
*.adocというファイルを作成します。
api-guide.adocの中で、
SpringRESTDocsで生成したsnippets
をincludeすることができます。
親adocは、公式ドキュメントにのっている
sample projectのapi-guide.adocを参考にして
作ってみるのがいいかと思います。
43
https://raw.githubusercontent.com/spring-pro...
親adocがある状態でもう一度buildしてみると、、
動きます
44
ついにhtmlが
45
指定した形式に変換されたapi-guide.*が作成されます。
pom.xml
もちろん開くことができます。
46
もう一つ
47
jarに内包させることが可能です。(アプリの中に入れる)
48
jarに内包させることが可能です。
49
pom.xml
Spring MVC Test
おさらい
50
1.SpringRESTDocsが部品(snippets)を作ってくれる(with SpringMVCTest)
2. snippetsをincludeする.adocファイルを作ると、ビルド時に
...
targetフォルダ
おさらい
51
targetの中にできるので、
例えばJenkinsとかのbuild
からドキュメントが参照できる
api-guide.html
appname.jar
api-guide.html
アプリの中にドキュメン...
SpringRESTDocsの何がいいのか
52
・(望むなら)testと一緒にdocumentが生成される
・testが通ったらdocumentがつくられるという仕組みを提供
・正しくないdocumentが限りなく作りにくい
・Wikiにあり...
Testからドキュメントを作ることのメリット
53
この結果はtest codeの中で実際にapiをcallして返ってきた値から作られている。
つまり仕様が変わればDocumentは変わる。
(HelloからGood mornningに変えれば...
かんがえること
・Test CodeとしてのDocumentation.javaの位置付け
(*Documentation.javaに書くテストは何のテストなのか)
Document how to separate REST documenti...
Appendix(Support Hypermedia format)
55
Spring sample project : https://spring.io/guides/gs/rest-hateoas/
Appendix(Parameter Description)
56
requestParameters/requestFields/responseFields
Appendix(Customize template)
57
Reference : http://docs.spring.io/spring-restdocs/docs/1.0.0.RELEASE/reference/html5/#docu...
1.0.1 coming soon.
58
Reference : https://github.com/spring-projects/spring-restdocs/milestones
1.0.1 がもうすぐでそうです : )
Thank you !
59
Upcoming SlideShare
Loading in …5
×

Spring oneを経験してよりよいwebサービスを作るために僕らが取り組むこと(document編)(SpringRESTDocs)

4,097 views

Published on

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

Published in: Technology
  • Swagger で「ライブラリのサイズ大きい(約31MB)」とあるんですが、ランタイムのサイズでしょうか? あまりにも大きすぎだと思いました。自分が計算したところ Spring Boot に Swagger UI 組み込んだとしても増えるのは 3.4MBでした。
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here

Spring oneを経験してよりよいwebサービスを作るために僕らが取り組むこと(document編)(SpringRESTDocs)

  1. 1. SpringOneを経験してよりよいWebサービスを作るために僕らが取り組むこと Takahiro Fujii Thomas Ludwig 1
  2. 2. Introduction 2 Takahiro Fujii(@taka_ft) Team Maneger Booking Front Team Travel Platform Group Travel Service Development Department
  3. 3. Agenda 3 https://jsug.doorkeeper.jp/events/34341
  4. 4. Spring REST Docsを利用して鮮度の高いDocumentを運用しよう Takahiro Fujii 4
  5. 5. Topic Documentation 5
  6. 6. 良いドキュメンテーションの仕組み ・良いドキュメンテーションの仕組みとはなにか ・簡単にドキュメントが作れる ・見やすいドキュメントを作成することができる ・ドキュメントを更新するコストが低い ・嘘をつかない(ドキュメントと実装の差分が発生しにくい) 6
  7. 7. 良いドキュメンテーションの仕組み Springを利用している アプリケーションではどうか? 7
  8. 8. Swagger 8 http://swagger.io/
  9. 9. Swaggerの考慮すべき点 ・URI baseのドキュメンテーション ・Documentationのためのコードがロジック側にはいる ・DRYではない (重複したコードをエンドポイント毎に定義する必要がある) ・Test-Driven Documentationしづらい ・Hypermediaをサポートしていない ・ライブラリのサイズ大きい(約31MB) ※Swaggerは良いツールです ※Sessionの動画でより具体的な点に触れています 9
  10. 10. 良いドキュメンテーションの仕組み ・良いドキュメンテーションの仕組みとはなにか ・見やすいデザインが作りやすい formatを使ってドキュメントを書くことができる ・ドキュメントを作成するために(ロジック側に)実装を必要としない ・ドキュメントが正確だと保証することができる 10
  11. 11. 良いドキュメンテーションの仕組み Springに適した ドキュメンテーションツール 11
  12. 12. 良いドキュメンテーションの仕組み 12 http://asciidoctor.org/
  13. 13. 良いドキュメンテーションの仕組み 13 http://docs.spring.io/spring-framework/docs/4.2.x/spring-framework-reference/htmlsingle/#spring-mvc-test-framework
  14. 14. 良いドキュメンテーションの仕組み Springに適した ドキュメンテーションツール 14
  15. 15. 良いドキュメンテーションの仕組み がAsciiDoctorとSpring MVC Test を軸に作られました。 15
  16. 16. Spring REST Docs 16 http://projects.spring.io/spring-restdocs/
  17. 17. 2015/10/07にでたばっかり! 17 https://github.com/spring-projects/spring-restdocs/releases
  18. 18. こんなものがつくれます(html) 18
  19. 19. こんなものがつくれます(自動生成してくれます) 19
  20. 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. 21. どのようにSpring REST Docsを使うか、 残りの時間でできる限り話します。 21
  22. 22. Spring REST Docs使ってみましょう Springのサンプル REST apiを Spring REST Docsを使って、 ドキュメンテーションを作成し てみます。 ※スライドを読み返してくれ ている方は、右のリンクから サンプルapiをチェックアウト して、実際にコードを書きな がら試してみることをお勧め します。 22 https://spring.io/guides/gs/rest-service/
  23. 23. イメージ src/test/javaの下に *Documentation.javaというクラス を作成します。 23 spring mvc testのテストコードに、 documentするためのmethodを追 加するようなイメージ
  24. 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. 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. 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. 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. 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. 29. static importが多いので 29 IDEでsuggestされるようにしておく(※上の図不完全)
  30. 30. さぁ、実装してみましょう 30 GreetingDocumentation.javaを実装してみましょう
  31. 31. 前処理 31 MockMvcのinstanceを作るときに、Documentationのoutputを指定
  32. 32. Actual code(Sample) 32 Build この3つの.adocファイルがビルド時に生成される(デフォルト) ※ここを変更するとdocumentが できるディレクトリを分けられます
  33. 33. adocって? .adocって何? 33
  34. 34. adocって? http://asciidoctor.org/docs/what-is-asciidoc/ 34
  35. 35. adocって? ・.adocはasciidoctorの拡張子 ・Markdownのようなマークアップ言語 ・HTMLやPDFなどに変換してくれる機能を有している 35
  36. 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. 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. で、これをどうすれば? 38
  39. 39. Spring REST Docsって何してくれるの? 39 http://projects.spring.io/spring-restdocs/ snippet : 切れ端・断片
  40. 40. SpringRESTDocsは snippets(断片) を自動生成してくれるもの 40
  41. 41. snippetsの親は自分で用意 41
  42. 42. 親adoc 42 src/main/asciidocの下に *.adocというファイルを作成します。 api-guide.adocの中で、 SpringRESTDocsで生成したsnippets をincludeすることができます。
  43. 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. 44. 親adocがある状態でもう一度buildしてみると、、 動きます 44
  45. 45. ついにhtmlが 45 指定した形式に変換されたapi-guide.*が作成されます。 pom.xml
  46. 46. もちろん開くことができます。 46
  47. 47. もう一つ 47
  48. 48. jarに内包させることが可能です。(アプリの中に入れる) 48
  49. 49. jarに内包させることが可能です。 49 pom.xml
  50. 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. 51. targetフォルダ おさらい 51 targetの中にできるので、 例えばJenkinsとかのbuild からドキュメントが参照できる api-guide.html appname.jar api-guide.html アプリの中にドキュメントを組み込み、 アプリ配下にドキュメントページ を組み込める
  52. 52. SpringRESTDocsの何がいいのか 52 ・(望むなら)testと一緒にdocumentが生成される ・testが通ったらdocumentがつくられるという仕組みを提供 ・正しくないdocumentが限りなく作りにくい ・Wikiにありがちな、更新されないdocumentを作らせない ・Test Driven Documentation ・(一度使い方を理解すれば)新規のアプリで動かすのが楽 ※最初はmockでapiを作っておいてドキュメントを先に用意して提供することも可能 テスト 成功 Create document start end false true
  53. 53. Testからドキュメントを作ることのメリット 53 この結果はtest codeの中で実際にapiをcallして返ってきた値から作られている。 つまり仕様が変わればDocumentは変わる。 (HelloからGood mornningに変えれば生成されるドキュメントも変わる) Endpointを変えてテストが失敗されればエラーがでてDocumentは生成されない ※もちろんMVC Testでもっと厳密な試験も可能
  54. 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. 55. Appendix(Support Hypermedia format) 55 Spring sample project : https://spring.io/guides/gs/rest-hateoas/
  56. 56. Appendix(Parameter Description) 56 requestParameters/requestFields/responseFields
  57. 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. 58. 1.0.1 coming soon. 58 Reference : https://github.com/spring-projects/spring-restdocs/milestones 1.0.1 がもうすぐでそうです : )
  59. 59. Thank you ! 59

×