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.
1 of 59

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

12

Share

Download to read offline

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

Related Books

Free with a 30 day trial from Scribd

See all

Related Audiobooks

Free with a 30 day trial from Scribd

See all

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

Editor's Notes

  • https://github.com/spring-projects/spring-restdocs/releases
  • https://github.com/spring-projects/spring-restdocs/releases
  • https://github.com/spring-projects/spring-restdocs/releases
  • https://github.com/spring-projects/spring-restdocs/releases
  • ×