Spring oneを経験してよりよいwebサービスを作るために僕らが取り組むこと(document編)(SpringRESTDocs)
Download as PPTX, PDF12 likes5,117 views
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
![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を直接開くとこんな感じです。](https://image.slidesharecdn.com/springonewebdocument-151207094452-lva1-app6892/85/Spring-one-web-document-SpringRESTDocs-36-320.jpg)
Spring oneを経験してよりよいwebサービスを作るために僕らが取り組むこと(document編)(SpringRESTDocs)
- 2. Introduction 2 Takahiro Fujii(@taka_ft) Team Maneger Booking Front Team Travel Platform Group Travel Service Development Department
- 17. 2015/10/07にでたばっかり！ 17 https://github.com/spring-projects/spring-restdocs/releases
- 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
- 22. Spring REST Docs使ってみましょう Springのサンプル REST apiを Spring REST Docsを使って、 ドキュメンテーションを作成し てみます。 ※スライドを読み返してくれ ている方は、右のリンクから サンプルapiをチェックアウト して、実際にコードを書きな がら試してみることをお勧め します。 22 https://spring.io/guides/gs/rest-service/
- 32. Actual code(Sample) 32 Build この3つの.adocファイルがビルド時に生成される(デフォルト) ※ここを変更するとdocumentが できるディレクトリを分けられます
- 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 : 切れ端・断片
- 47. もう一つ 47
- 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
- 52. SpringRESTDocsの何がいいのか 52 ・(望むなら)testと一緒にdocumentが生成される ・testが通ったらdocumentがつくられるという仕組みを提供 ・正しくないdocumentが限りなく作りにくい ・Wikiにありがちな、更新されないdocumentを作らせない ・Test Driven Documentation ・(一度使い方を理解すれば)新規のアプリで動かすのが楽 ※最初はmockでapiを作っておいてドキュメントを先に用意して提供することも可能 テスト 成功 Create document start end false true
- 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/
- 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
Editor's Notes
- #18: https://github.com/spring-projects/spring-restdocs/releases
- #19: https://github.com/spring-projects/spring-restdocs/releases
- #20: https://github.com/spring-projects/spring-restdocs/releases
- #54: https://github.com/spring-projects/spring-restdocs/releases