RESTful API를 제공 하면서 API 문서를 항상 만들었습니다. 시간이 지남에 따라 제공된 API의 기능들은 추가 되거나 변경/삭제 되어 갔지만, 그에 반해 API 문서는 관리 소홀로 결국에는 불일치(API!=DOC)되면서 겪게 되는 API 문서 관리의 어려움을 우리는 자주 만나고 있습니다. 현재 한참 개발이 진행중인 스프링 프로젝트 중 Spring REST Docs를 사용해 API 문서를 손쉽게 자동으로 생성하고, 테스트까지 함께 할 수 있는 지에 대한 경험을 공유하고자 합니다. Swagger를 넘어 이제는 Spring REST Docs으로... 이 세션에서는 Spring REST Docs + MVC Test 두 마리 토끼를 한번에 잡을 수 있는 방법을 살펴보고자 합니다.

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. 99

3. TestTest
DocumentDocument
"테스트 작성은 어렵지 않다. 단지 좋아하지 않을 뿐이다."
"잘 작성되고 설명이 풍부하면서 동시에 간결한 문서 작성하기"
http://www.itworld.co.kr/slideshow/85296

6. *.adoc*.adoc

7. *.adoc*.adoc *.html*.html
more

10. RequestRequest
ResponseResponse

12. index.adocindex.adoc

13. *.adoc
index.adoc

14. *.adoc
index.adoc

15. index.adoc
....................
.......................................................
spring rest docs.......
curl http://127......................
RESTful API Docuemtns
*.adoc

16. mvc test auto

18. Appointment RESTful APIAppointment RESTful API
DocumentsDocuments

19. /doctors/doctors
/patients/patients
/schedules/schedules

21. //
{
"timestamp": "2015-10-296 10:49:34",
"status": 404,
"error": "Not Found",
"message": "No message available",
"path": "/"
}

22. /doctors/doctors
{
"doctors": [
{
"id": 1,
"name": "doctor_name_1"
},
{
"id": 2,
"name": "doctor_name_2"
},
..................
]
}

23. http://stateless.co/hal_specification.html
HATEOASHATEOASHypermedia as the Engine of Application State

24. //
{
"_links": {
"doctors": {
"href": "http://localhost:8080/doctors"
},
"patient": {
"href": "http://localhost:8080/patients"
},
"schedule": {
"href": "http://localhost:8080/schedules"
}
}
}

25. /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"
},

26. Richardson Maturity ModelRichardson Maturity Model
http://martinfowler.com/articles/richardsonMaturityModel.html

27. 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'

28. @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();
}

29. @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
}

30. :test:test
:asciidoctor:asciidoctor
:jar:jar

31. index.adoc
....................
.......................................................
spring rest docs.......
curl http://127......................
RESTful API Docuemtns
*.adoc

32. index.adoc
overview.adoc
resources.adoc
overview-current.adoc
..........*.adoc
.....*.adoc
resources-doctors.adoc
..........*.adoc
.....*.adoc

33. 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

34. 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
..........
........
......
....
..

35. 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

36. mvc test auto

37. overview.html
resources.html
overview-current.html
..........*.html
.....*.html
resources-doctors.html
..........*.html
.....*.html
index.html

38. build/asciidocbuild/asciidoc
/generated-sn~/generated-sn~
src/main/asciidocsrc/main/asciidoc
src/main/resourcessrc/main/resources
/static/docs/static/docs

39. http://gmind7.github.io/docs.htmlhttp://gmind7.github.io/docs.html

41. 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

42. https://github.com/gmind7https://github.com/gmind7
/spring-rest-docs-seminar/spring-rest-docs-seminar

43. Making your API easy to document withMaking your API easy to document with
Spring REST DocsSpring REST Docs
The End.The End.