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.
Making your API easy to document withMaking your API easy to document with
Spring REST DocsSpring REST Docs
http://gmind7....
99
TestTest
DocumentDocument
"테스트 작성은 어렵지 않다. 단지 좋아하지 않을 뿐이다."
"잘 작성되고 설명이 풍부하면서 동시에 간결한 문서 작성하기"
http://www.itworld.co.kr/sl...
*.adoc*.adoc
*.adoc*.adoc *.html*.html
more
RequestRequest
ResponseResponse
index.adocindex.adoc
*.adoc
index.adoc
*.adoc
index.adoc
index.adoc
....................
.......................................................
spring rest docs.......
curl http:...
mvc test auto
Appointment RESTful APIAppointment RESTful API
DocumentsDocuments
/doctors/doctors
/patients/patients
/schedules/schedules
//
{
"timestamp": "2015-10-296 10:49:34",
"status": 404,
"error": "Not Found",
"message": "No message available",
"path": ...
/doctors/doctors
{
"doctors": [
{
"id": 1,
"name": "doctor_name_1"
},
{
"id": 2,
"name": "doctor_name_2"
},
.................
http://stateless.co/hal_specification.html
HATEOASHATEOASHypermedia as the Engine of Application State
//
{
"_links": {
"doctors": {
"href": "http://localhost:8080/doctors"
},
"patient": {
"href": "http://localhost:8080/patie...
/doctors/doctors
{
"_links": {
"self": {
"href": "http://localhost:8080/doctors{?page,size,sort}
"templated": true
},
"nex...
Richardson Maturity ModelRichardson Maturity Model
http://martinfowler.com/articles/richardsonMaturityModel.html
plugins {
id "org.asciidoctor.convert" version "1.5.2"
}
dependencies {
testCompile 'org.springframework.restdocs:spring-r...
@Rule
public final RestDocumentation restDocumentation =
new RestDocumentation("build/generated-snippets");
@Autowired
pri...
@Test
public void doctorsShowAll() throws Exception {
this.mockMvc.perform(get("/doctors").param("page","2").param("s
.and...
:test:test
:asciidoctor:asciidoctor
:jar:jar
index.adoc
....................
.......................................................
spring rest docs.......
curl http:...
index.adoc
overview.adoc
resources.adoc
overview-current.adoc
..........*.adoc
.....*.adoc
resources-doctors.adoc
...........
C:spring-rest-docs-seminar
srcmainasciidoc>tree /F
C:.
│ index.adoc
│
├─overview
│ overview-current-version.adoc
│ overvie...
C:spring-rest-docs-seminar
buildgenerated-snippets>tree /F
C:.
├─doctors-show-all
│ curl-request.adoc
│ http-request.adoc
...
C:.
├─doctors-show-all
│ curl-request.adoc
│ http-request.adoc
│ http-response.adoc
│ links.adoc
│ request-parameters.adoc...
mvc test auto
overview.html
resources.html
overview-current.html
..........*.html
.....*.html
resources-doctors.html
..........*.html
.....
build/asciidocbuild/asciidoc
/generated-sn~/generated-sn~
src/main/asciidocsrc/main/asciidoc
src/main/resourcessrc/main/re...
http://gmind7.github.io/docs.htmlhttp://gmind7.github.io/docs.html
build.gradle || pom.xmlbuild.gradle || pom.xml
Spring MVC TESTSpring MVC TEST
.andDo(Spring REST Docs).andDo(Spring REST D...
https://github.com/gmind7https://github.com/gmind7
/spring-rest-docs-seminar/spring-rest-docs-seminar
Making your API easy to document withMaking your API easy to document with
Spring REST DocsSpring REST Docs
The End.The En...
Making your API easy to document with Spring REST Docs
Making your API easy to document with Spring REST Docs
Making your API easy to document with Spring REST Docs
Making your API easy to document with Spring REST Docs
Making your API easy to document with Spring REST Docs
Making your API easy to document with Spring REST Docs
Making your API easy to document with Spring REST Docs
Making your API easy to document with Spring REST Docs
Upcoming SlideShare
Loading in …5
×

Making your API easy to document with Spring REST Docs

RESTful API를 제공 하면서 API 문서를 항상 만들었습니다.
시간이 지남에 따라 제공된 API의 기능들은 추가 되거나 변경/삭제 되어 갔지만, 그에 반해 API 문서는 관리 소홀로 결국에는 불일치(API!=DOC)되면서 겪게 되는 API 문서 관리의 어려움을 우리는 자주 만나고 있습니다.

현재 한참 개발이 진행중인 스프링 프로젝트 중 Spring REST Docs를 사용해 API 문서를 손쉽게 자동으로 생성하고, 테스트까지 함께 할 수 있는 지에 대한 경험을 공유하고자 합니다.
Swagger를 넘어 이제는 Spring REST Docs으로...

이 세션에서는 Spring REST Docs + MVC Test 두 마리 토끼를 한번에 잡을 수 있는 방법을 살펴보고자 합니다.

  • Be the first to comment

Making your API easy to document with Spring REST Docs

  1. 1. Making your API easy to document withMaking your API easy to document with Spring REST DocsSpring REST Docs http://gmind7.github.io Java Softeware Developer
  2. 2. 99
  3. 3. TestTest DocumentDocument "테스트 작성은 어렵지 않다. 단지 좋아하지 않을 뿐이다." "잘 작성되고 설명이 풍부하면서 동시에 간결한 문서 작성하기" http://www.itworld.co.kr/slideshow/85296
  4. 4. *.adoc*.adoc
  5. 5. *.adoc*.adoc *.html*.html more
  6. 6. RequestRequest ResponseResponse
  7. 7. index.adocindex.adoc
  8. 8. *.adoc index.adoc
  9. 9. *.adoc index.adoc
  10. 10. index.adoc .................... ....................................................... spring rest docs....... curl http://127...................... RESTful API Docuemtns *.adoc
  11. 11. mvc test auto
  12. 12. Appointment RESTful APIAppointment RESTful API DocumentsDocuments
  13. 13. /doctors/doctors /patients/patients /schedules/schedules
  14. 14. // { "timestamp": "2015-10-296 10:49:34", "status": 404, "error": "Not Found", "message": "No message available", "path": "/" }
  15. 15. /doctors/doctors { "doctors": [ { "id": 1, "name": "doctor_name_1" }, { "id": 2, "name": "doctor_name_2" }, .................. ] }
  16. 16. http://stateless.co/hal_specification.html HATEOASHATEOASHypermedia as the Engine of Application State
  17. 17. // { "_links": { "doctors": { "href": "http://localhost:8080/doctors" }, "patient": { "href": "http://localhost:8080/patients" }, "schedule": { "href": "http://localhost:8080/schedules" } } }
  18. 18. /doctors/doctors { "_links": { "self": { "href": "http://localhost:8080/doctors{?page,size,sort} "templated": true }, "next": { "href": "http://localhost:8080/doctors?page=1&size=10{& "templated": true } }, "_embedded": { "doctors": [ { "id": 1, "name": "doctor_name_1", "_links": { "self": { "href": "http://127.0.0.1:8080/doctors/1" },
  19. 19. Richardson Maturity ModelRichardson Maturity Model http://martinfowler.com/articles/richardsonMaturityModel.html
  20. 20. plugins { id "org.asciidoctor.convert" version "1.5.2" } dependencies { testCompile 'org.springframework.restdocs:spring-restdocs-mockm } ext { snippetsDir = file('build/generated-snippets') } test { outputs.dir snippetsDir } asciidoctor { attributes 'snippets': snippetsDir inputs.dir snippetsDir dependsOn test } jar { dependsOn asciidoctor from ("${asciidoctor.outputDir}/html5") { into 'static/docs'
  21. 21. @Rule public final RestDocumentation restDocumentation = new RestDocumentation("build/generated-snippets"); @Autowired private WebApplicationContext context; public RestDocumentationResultHandler document; public MockMvc mockMvc; @Before public void setUp() { this.document = document("{method-name}"); this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context) .apply(documentationConfiguration(this.restDocumentatio .uris().withScheme("http").withHost("root-endpo .alwaysDo(this.document) .build(); }
  22. 22. @Test public void doctorsShowAll() throws Exception { this.mockMvc.perform(get("/doctors").param("page","2").param("s .andExpect(status().isOk()) .andDo(this.document.snippets( links( linkWithRel("next").optional().description("다음페이지 linkWithRel("prev").optional().description("이전페이지 linkWithRel("self").description("현재페이지")), requestParameters( parameterWithName("page").description("페이지 번호"), parameterWithName("size").description("리스트 사이즈")) responseFields( fieldWithPath("_links").type(JsonFieldType.OBJECT). fieldWithPath("_embedded.doctors").type(JsonFieldTy fieldWithPath("page").type(JsonFieldType.OBJECT).de }
  23. 23. :test:test :asciidoctor:asciidoctor :jar:jar
  24. 24. index.adoc .................... ....................................................... spring rest docs....... curl http://127...................... RESTful API Docuemtns *.adoc
  25. 25. index.adoc overview.adoc resources.adoc overview-current.adoc ..........*.adoc .....*.adoc resources-doctors.adoc ..........*.adoc .....*.adoc
  26. 26. C:spring-rest-docs-seminar srcmainasciidoc>tree /F C:. │ index.adoc │ ├─overview │ overview-current-version.adoc │ overview-schema.adoc │ overview-parameters.adoc │ overview-root-endpoint.adoc │ ........... │ ....... │ .. │ ├─resources │ resources-doctors.adoc │ resources-index.adoc │ resources-patients.adoc │ resources-schedules.adoc
  27. 27. C:spring-rest-docs-seminar buildgenerated-snippets>tree /F C:. ├─doctors-show-all │ curl-request.adoc │ http-request.adoc │ http-response.adoc │ links.adoc │ request-parameters.adoc │ response-fields.adoc │ └─doctors-show-one curl-request.adoc http-request.adoc http-response.adoc links.adoc path-parameters.adoc response-fields.adoc .......... ........ ...... .... ..
  28. 28. C:. ├─doctors-show-all │ curl-request.adoc │ http-request.adoc │ http-response.adoc │ links.adoc │ request-parameters.adoc │ response-fields.adoc C:spring-rest-docs-seminar srcmainasciidoc>tree /F C:. │ index.adoc │ ├─overview │ overview-current-version.adoc │ overview-schema.adoc │ overview-parameters.adoc │ overview-root-endpoint.adoc │ ........... │ ....... │ .. │ ├─resources │ resources-doctors.adoc │ resources-index.adoc │ resources-patients.adoc │ resources-schedules.adoc
  29. 29. mvc test auto
  30. 30. overview.html resources.html overview-current.html ..........*.html .....*.html resources-doctors.html ..........*.html .....*.html index.html
  31. 31. build/asciidocbuild/asciidoc /generated-sn~/generated-sn~ src/main/asciidocsrc/main/asciidoc src/main/resourcessrc/main/resources /static/docs/static/docs
  32. 32. http://gmind7.github.io/docs.htmlhttp://gmind7.github.io/docs.html
  33. 33. build.gradle || pom.xmlbuild.gradle || pom.xml Spring MVC TESTSpring MVC TEST .andDo(Spring REST Docs).andDo(Spring REST Docs) index.adocindex.adoc include::resources-*.adocinclude::resources-*.adoc include::**-restdocs.adocinclude::**-restdocs.adoc index.htmlindex.html
  34. 34. https://github.com/gmind7https://github.com/gmind7 /spring-rest-docs-seminar/spring-rest-docs-seminar
  35. 35. Making your API easy to document withMaking your API easy to document with Spring REST DocsSpring REST Docs The End.The End.

×