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...
良いドキュメンテーションの仕組み がAsciiDoctorとSpring MVC Test を軸に作られました。 14
Spring REST Docs 15 http://projects.spring.io/spring-restdocs/
2015/10/07にでたばっかり！ 16 https://github.com/spring-projects/spring-restdocs/releases
こんなものがつくれます 17
こんなものがつくれます(自動生成してくれます） 18
SpringOne’s session Spring REST DocsはどのようにREST APIのドキュメ ンテーションを助けてくれるのか DOCUMENTING RESTFUL APIS https://2015.event.spring...
どのようにSpring REST Docsを使うか、 残りの時間でできる限り話します。 20
Spring REST Docs使ってみましょう Springのサンプル REST apiを Spring REST Docsを使って、 ドキュメンテーションを作成し てみます。 ※スライドを読み返してくれ ている方は、右のリンクから サンプル...
イメージ src/test/javaの下に *Documentation.javaというクラス を作成します。 22 spring mvc testのテストコードに、 documentするためのmethodを追 加するようなイメージ
dependency/build設定の追加 23 http://docs.spring.io/spring-restdocs/docs/1.0.0.RELEASE/reference/html5/#getting-started-build-c...
dependency/build設定の追加(1) 24 http://docs.spring.io/spring-restdocs/docs/1.0.0.RELEASE/reference/html5/#getting-started-buil...
dependency/build設定の追加(2) 25 http://docs.spring.io/spring-restdocs/docs/1.0.0.RELEASE/reference/html5/#getting-started-buil...
dependency/build設定の追加(3) 26 http://docs.spring.io/spring-restdocs/docs/1.0.0.RELEASE/reference/html5/#getting-started-buil...
dependency/build設定の追加(4) 27 http://docs.spring.io/spring-restdocs/docs/1.0.0.RELEASE/reference/html5/#getting-started-buil...
static importが多いので 28 IDEでsuggestされるようにしておく
さぁ、実装してみましょう 29 GreetingDocumentation.javaを実装してみましょう
前処理 30 MockMvcのinstanceを作るときに、Documentationのoutputを指定
Actual code(Sample) 31 Build この3つの.adocファイルがビルド時に生成される(デフォルト) ※ここを変更するとdocumentが できるディレクトリを分けられます
adocって？ .adocって何？ 32
adocって？ http://asciidoctor.org/docs/what-is-asciidoc/ 33
adocって？ ・.adocはasciidoctorの拡張子 ・Markdownのようなマークアップ言語 ・HTMLやPDFなどに変換してくれる機能を有している 34
adocって？ 35 [source,bash] ---- $ curl 'http://localhost:8080/greeting?name=takahiro' –I ---- [source,http] ---- GET /greeti...
adocって？(対応 36 curl-request.adoc http-request.adoc http-response.adoc add-on,plugin firefox : https://addons.mozilla.org/ja...
で、これをどうすれば？ 37
Spring REST Docsって何してくれるの？ 38 http://projects.spring.io/spring-restdocs/ snippet : 切れ端・断片
SpringRESTDocsは snippets(断片) を自動生成してくれるもの 39
snippetsの親は自分で用意 40
親adoc 41 src/main/asciidocの下に *.adocというファイルを作成します。 api-guide.adocの中で、 SpringRESTDocsで生成したsnippets をincludeすることができます。
親adocは、公式ドキュメントにのっている sample projectのapi-guide.adocを参考にして 作ってみるのがいいかと思います。 42 https://raw.githubusercontent.com/spring-pro...
親adocがある状態でもう一度buildしてみると、、 動きます 43
ついにhtmlが 44 指定した形式に変換されたapi-guide.*が作成されます。 pom.xml
もちろん開くことができます。 45
もう一つ 46
jarに内包させることが可能です。(アプリの中に入れる) 47
jarに内包させることが可能です。 48 pom.xml
Spring MVC Test おさらい 49 1.SpringRESTDocsが部品(snippets)を作ってくれる(with SpringMVCTest) 2. snippetsをincludeする.adocファイルを作ると、ビルド時に ...
targetフォルダ おさらい 50 targetの中にできるので、 例えばJenkinsとかのbuild からドキュメントが参照できる api-guide.html appname.jar api-guide.html アプリの中にドキュメン...
SpringRESTDocsの何がいいのか 51 ・(望むなら)testと一緒にdocumentが生成される ・testが通ったらdocumentがつくられるという仕組みを提供 ・正しくないdocumentが限りなく作りにくい ・Wikiにあり...
かんがえること ・Test CodeとしてのDocumentation.javaの位置付け (*Documentation.javaに書くテストは何テストなのか) Document how to separate REST documentin...
Appendix(Support Hypermedia format) 53 Spring sample project : https://spring.io/guides/gs/rest-hateoas/
Appendix(Parameter Description) 54 requestParameters/requestFields/responseFields
Appendix(Customize template) 55 Reference : http://docs.spring.io/spring-restdocs/docs/1.0.0.RELEASE/reference/html5/#docu...
1.0.1 coming soon. 56 Reference : https://github.com/spring-projects/spring-restdocs/milestones 1.0.1 がもうすぐでそうです : )
Thank you ! 57
Upcoming SlideShare
Loading in...5
×

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

117
 -1

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
0 Comments
3 Likes
Statistics
Notes
no profile picture user

  • Be the first to comment

No Downloads
Views
Total Views
117
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
0
Comments
0
Likes
3
Embeds 0
No embeds

No notes for slide
  • https://github.com/spring-projects/spring-restdocs/releases
  • https://github.com/spring-projects/spring-restdocs/releases
  • https://github.com/spring-projects/spring-restdocs/releases

    • 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. 良いドキュメンテーションの仕組み がAsciiDoctorとSpring MVC Test を軸に作られました。 14
    15. 15. Spring REST Docs 15 http://projects.spring.io/spring-restdocs/
    16. 16. 2015/10/07にでたばっかり！ 16 https://github.com/spring-projects/spring-restdocs/releases
    17. 17. こんなものがつくれます 17
    18. 18. こんなものがつくれます(自動生成してくれます） 18
    19. 19. 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 19
    20. 20. どのようにSpring REST Docsを使うか、 残りの時間でできる限り話します。 20
    21. 21. Spring REST Docs使ってみましょう Springのサンプル REST apiを Spring REST Docsを使って、 ドキュメンテーションを作成し てみます。 ※スライドを読み返してくれ ている方は、右のリンクから サンプルapiをチェックアウト して、実際にコードを書きな がら試してみることをお勧め します。 21 https://spring.io/guides/gs/rest-service/
    22. 22. イメージ src/test/javaの下に *Documentation.javaというクラス を作成します。 22 spring mvc testのテストコードに、 documentするためのmethodを追 加するようなイメージ
    23. 23. dependency/build設定の追加 23 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 まずは公式ドキュメントに書いてある設定を使ってみてください。 各項目で何をしているかの説明も記載されています。
    24. 24. dependency/build設定の追加(1) 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 Dependencyとして追加するのはこれだけ (そのうちstarterに入りそうな気もします)
    25. 25. dependency/build設定の追加(2) 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 *Documentation.javaをunit testの実行対象にします
    26. 26. dependency/build設定の追加(3) 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 ドキュメント(.adoc形式)をhtmlに変換するために必要です(他の形式にも変更可能)（後述します) ※公式ドキュメントではpropertiesで この値をsnippetsDirectoryで定義しています
    27. 27. dependency/build設定の追加(4) 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 生成されたdocumentをjarの中に内包したい場合必要（後述します)
    28. 28. static importが多いので 28 IDEでsuggestされるようにしておく
    29. 29. さぁ、実装してみましょう 29 GreetingDocumentation.javaを実装してみましょう
    30. 30. 前処理 30 MockMvcのinstanceを作るときに、Documentationのoutputを指定
    31. 31. Actual code(Sample) 31 Build この3つの.adocファイルがビルド時に生成される(デフォルト) ※ここを変更するとdocumentが できるディレクトリを分けられます
    32. 32. adocって？ .adocって何？ 32
    33. 33. adocって？ http://asciidoctor.org/docs/what-is-asciidoc/ 33
    34. 34. adocって？ ・.adocはasciidoctorの拡張子 ・Markdownのようなマークアップ言語 ・HTMLやPDFなどに変換してくれる機能を有している 34
    35. 35. adocって？ 35 [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を直接開くとこんな感じです。
    36. 36. adocって？(対応 36 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 対応しているブラウザ/ソフト で開くとこんな感じに表示されます。
    37. 37. で、これをどうすれば？ 37
    38. 38. Spring REST Docsって何してくれるの？ 38 http://projects.spring.io/spring-restdocs/ snippet : 切れ端・断片
    39. 39. SpringRESTDocsは snippets(断片) を自動生成してくれるもの 39
    40. 40. snippetsの親は自分で用意 40
    41. 41. 親adoc 41 src/main/asciidocの下に *.adocというファイルを作成します。 api-guide.adocの中で、 SpringRESTDocsで生成したsnippets をincludeすることができます。
    42. 42. 親adocは、公式ドキュメントにのっている sample projectのapi-guide.adocを参考にして 作ってみるのがいいかと思います。 42 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
    43. 43. 親adocがある状態でもう一度buildしてみると、、 動きます 43
    44. 44. ついにhtmlが 44 指定した形式に変換されたapi-guide.*が作成されます。 pom.xml
    45. 45. もちろん開くことができます。 45
    46. 46. もう一つ 46
    47. 47. jarに内包させることが可能です。(アプリの中に入れる) 47
    48. 48. jarに内包させることが可能です。 48 pom.xml
    49. 49. Spring MVC Test おさらい 49 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
    50. 50. targetフォルダ おさらい 50 targetの中にできるので、 例えばJenkinsとかのbuild からドキュメントが参照できる api-guide.html appname.jar api-guide.html アプリの中にドキュメントを組み込み、 アプリ配下にドキュメントページ を組み込める
    51. 51. SpringRESTDocsの何がいいのか 51 ・(望むなら)testと一緒にdocumentが生成される ・testが通ったらdocumentがつくられるという仕組みを提供 ・正しくないdocumentが限りなく作りにくい ・Wikiにありがちな、更新されないdocumentを作らせない ・Test Driven Documentation ・(一度使い方を理解すれば)新規のアプリで動かすの楽 ※最初はmockでapiを作っておいてドキュメントを先に用意して提供することも可能 テスト 成功 Create document start end false true
    52. 52. かんがえること ・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でつくられるドキュメントは誰のためのドキュメント？) （例えばこのドキュメンテーションを外部に出せる状態で常に維持するのか エンジニアのためのものか） 52
    53. 53. Appendix(Support Hypermedia format) 53 Spring sample project : https://spring.io/guides/gs/rest-hateoas/
    54. 54. Appendix(Parameter Description) 54 requestParameters/requestFields/responseFields
    55. 55. Appendix(Customize template) 55 Reference : http://docs.spring.io/spring-restdocs/docs/1.0.0.RELEASE/reference/html5/#documenting-your-api-customizing-snippets
    56. 56. 1.0.1 coming soon. 56 Reference : https://github.com/spring-projects/spring-restdocs/milestones 1.0.1 がもうすぐでそうです : )
    57. 57. Thank you ! 57

    1. A particular slide catching your eye?

      Clipping is a handy way to collect important slides you want to go back to later.

    ×