Upload
-
View
1.908
Download
6
Embed Size (px)
Citation preview
Making your API easy to document withMaking your API easy to document withSpring REST Docs Spring REST Docs
http://gmind7.github.ioJava Softeware Developer
99
TestTest
DocumentDocument
"테스트 작성은 어렵지 않다. 단지 좋아하지 않을 뿐이다."
"잘 작성되고 설명이 풍부하면서 동시에 간결한 문서 작성하기"
http://www.itworld.co.kr/slideshow/85296
*.adoc*.adoc
*.adoc*.adoc *.html*.htmlmore
RequestRequestResponseResponse
index.adocindex.adoc
*.adoc
index.adoc
*.adoc
index.adoc
index.adoc
...........................................................................
spring rest docs.......
curl http://127......................
RESTful API Docuemtns
*.adoc
mvc test auto
Appointment RESTful APIAppointment RESTful APIDocumentsDocuments
/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/patients" }, "schedule": { "href": "http://localhost:8080/schedules" } }}
/doctors /doctors{ "_links": { "self": { "href": "http://localhost:8080/doctors{?page,size,sort}" "templated": true }, "next": { "href": "http://localhost:8080/doctors?page=1&size=10{&sort}" "templated": true } }, "_embedded": { "doctors": [ { "id": 1, "name": "doctor_name_1", "_links": { "self": { "href": "http://127.0.0.1:8080/doctors/1" },
Richardson Maturity Model Richardson Maturity Model
http://martinfowler.com/articles/richardsonMaturityModel.html
plugins { id "org.asciidoctor.convert" version "1.5.2"}dependencies { testCompile 'org.springframework.restdocs:spring-restdocs-mockmvc:1.0.0.RELEASE'}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'
@Rulepublic final RestDocumentation restDocumentation = new RestDocumentation("build/generated-snippets");
@Autowiredprivate WebApplicationContext context;
public RestDocumentationResultHandler document;
public MockMvc mockMvc;
@Beforepublic void setUp() { this.document = document("{method-name}"); this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context) .apply(documentationConfiguration(this.restDocumentation) .uris().withScheme("http").withHost("root-endpoint" .alwaysDo(this.document) .build();}
@Testpublic void doctorsShowAll() throws Exception { this.mockMvc.perform(get("/doctors").param("page","2").param("size" .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).description( fieldWithPath("_embedded.doctors").type(JsonFieldType.OBJECT).description( fieldWithPath("page").type(JsonFieldType.OBJECT).description(}
:test:test
:asciidoctor:asciidoctor
:jar:jar
index.adoc
...........................................................................
spring rest docs.......
curl http://127......................
RESTful API Docuemtns
*.adoc
index.adoc
overview.adoc
resources.adoc
overview-current.adoc..........*.adoc.....*.adoc
resources-doctors.adoc..........*.adoc.....*.adoc
C:\spring-rest-docs-seminar\src\main\asciidoc>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
C:\spring-rest-docs-seminar\build\generated-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..............................
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\src\main\asciidoc>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
mvc test auto
overview.html
resources.html
overview-current.html..........*.html.....*.html
resources-doctors.html..........*.html.....*.html
index.html
build/asciidocbuild/asciidoc
/generated-sn~ /generated-sn~
src/main/asciidocsrc/main/asciidoc
src/main/resourcessrc/main/resources
/static/docs/static/docs
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 Docs)
index.adoc index.adoc
include::resources-*.adoc include::resources-*.adoc
include::**-restdocs.adoc include::**-restdocs.adoc
index.htmlindex.html
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 withSpring REST Docs Spring REST Docs
The End.The End.