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.