Making your API easy to document with Spring REST Docs
Transcript of Making your API easy to document with Spring REST Docs
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.