Download as PDF, PPTX
![/doctors/doctors
{
"doctors": [
{
"id": 1,
"name": "doctor_name_1"
},
{
"id": 2,
"name": "doctor_name_2"
},
..................
]
}](https://image.slidesharecdn.com/spirngrestdocs-pdf-151026013932-lva1-app6892/85/Making-your-API-easy-to-document-with-Spring-REST-Docs-22-320.jpg)
Uploaded byNAVER / MusicPlatform
Making your API easy to document with Spring REST Docs
The document discusses how to create documentation for APIs using Spring REST Docs, emphasizing the importance of clear and concise documentation. It outlines the directory structure and various resources needed for generating API documentation, including examples for managing doctors, patients, and schedules. The document also details code snippets and configurations required for proper integration with Spring MVC testing.
Making your API easy to document with Spring REST Docs
- 1. Making your APIeasy to document withMaking your API easy to document with Spring REST DocsSpring REST Docs http://gmind7.github.io Java Softeware Developer
- 2.
- 3. TestTest DocumentDocument "테스트 작성은 어렵지않다. 단지 좋아하지 않을 뿐이다." "잘 작성되고 설명이 풍부하면서 동시에 간결한 문서 작성하기" http://www.itworld.co.kr/slideshow/85296
- 6.
- 7.
- 10.
- 12.
- 13.
- 14.
- 15. index.adoc .................... ....................................................... spring rest docs....... curlhttp://127...................... RESTful API Docuemtns *.adoc
- 16.
- 18. Appointment RESTful APIAppointmentRESTful API DocumentsDocuments
- 19.
- 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 theEngine 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 ModelRichardsonMaturity 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 RestDocumentationrestDocumentation = 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.
- 31. index.adoc .................... ....................................................... spring rest docs....... curlhttp://127...................... RESTful API Docuemtns *.adoc
- 32.
- 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.
- 37.
- 38.
- 39.
- 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.
- 43. Making your APIeasy to document withMaking your API easy to document with Spring REST DocsSpring REST Docs The End.The End.