Transcript
RESTful API 문서화
Spring REST Docs
made by jylee 1
이해와 따라 하기
made by jylee 2
API와 API문서화
다른 서비스에 요청을 보내고 응답을 받기 위해 정의된 명세
• API
제공하는 API 서비스의 로직을 문서로 기술하는 것
• API 문서화
made by jylee 3
API와 API문서화
made by jylee 4
API문서화 툴
Wiki
made by jylee 5
API문서화 툴
• 주석을 통한 문서화
• 아직 테스트가 필요한 단계
made by jylee 6
API문서화 툴
• JSON 파싱을 통한 문서화
• Node.js 와 Redis 설치 필요
made by jylee 7
API문서화 툴
made by jylee 8
API문서화 툴
• Annotation을 사용한 문서화
• 개발 기능과 문서와의 싱크 ↑
• 그러나 복잡해지는 소스코드
made by jylee 9
API문서화 툴
• Annotation을 사용한 문서화
• 개발 기능과 문서와의 싱크 ↑
• 그러나 복잡해지는 소스코드
made by jylee 10
Spring REST Docs?
We made tool
Spring REST Docs
made by jylee 11
Spring REST Docs?
+@Test
Mock Test
+
made by jylee 12
Spring REST Docs?
=
made by jylee 13
API-Guide.adoc
include
maven-resources-plugin
API-Guide.html*documentation.java
@Test//단위테스트document(“index”)
Snippets
Spring REST Docs!
~asciiDotor~
made by jylee 14
REST Docs 시작하기 - 설정
1. Spring Starter Project로 새로운 Spring 프로젝트를 생성
- STS : 우클릭/new/Spring Starter Project
2-1. Spring Boot로 생성시 REST Docs 체크
2-2. pom.xml에서 Maven dependency 추가 설정 (RESTDocs)
<dependency><groupId>org.springframework.restdocs</groupId><artifactId>spring-restdocs-mockmvc</artifactId><version>1.0.1.RELEASE</version><scope>test</scope></dependency>
made by jylee 15
REST Docs 시작하기 - 설정
3. pom.xml 파일에서 snippetsDirectory 설정
- 프로젝트가 빌드되는 곳(target)에 디렉토리 생성
<properties><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><java.version>1.7</java.version><snippetsDirectory>
${project.build.directory}/generated-snippets</snippetsDirectory><spring-restdocs.version>
1.1.0.BUILD-SNAPSHOT</spring-restdocs.version></properties>
made by jylee 16
REST Docs 시작하기 - 설정
4. pom.xml 파일에서 plugin 설정
4-1. maven-surefire-plugin 설정
- surefire 플러그인은 단위테스트를 위한 플러그인
<plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-plugin</artifactId><configuration>
<includes>
<include>**/*Documentation.java</include></includes>
</configuration></plugin>
made by jylee 17
REST Docs 시작하기 - 설정
4. pom.xml 파일에서 plugin 설정
4-2. asciidoctor-maven-plugin 설정
- asciiodctor 문법을 사용하기 위한 plugin 설정
<plugin><groupId>org.asciidoctor</groupId><artifactId>asciidoctor-maven-plugin</artifactId><version>1.5.3</version><executions><execution>
<id>generate-docs</id><phase>prepare-package</phase><goals><goal>process-asciidoc</goal></goals><configuration>
<backend>html</backend><doctype>book</doctype><attributes>
<snippets>${project.build.directory}/generated-snippets</snippets></attributes>
</configuration></execution></executions>
</plugin>
made by jylee 18
REST Docs 시작하기 - 설정
4. pom.xml 파일에서 plugin 설정
4-3. maven-resources-plugin 설정
- Asciidoctor플러그인 후에 동작되어야 함
- phase(prepare-package)에 묶임
<plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-resources-plugin</artifactId><executions><execution>
<id>copy-resources</id><phase>prepare-package</phase><goals>
<goal>copy-resources</goal></goals><configuration>
<outputDirectory>${project.build.outputDirectory}/static/docs</outputDirectory><resources><resource>
<directory>${project.build.directory}/generated-docs</directory></resource></resources>
</configuration></execution></executions>
</plugin>
made by jylee 19
REST Docs 시작하기 - MockMVC
1. *documentation.java 파일을 생성
2. 단위 테스트 작성
@Testpublic void test() throws Exception{
//해당 url을 실행this.mockMvc.perform(get("/member/").accept(MediaType.APPLICATION_JSON))
//응답 성공을 가정.andExpect(status().isOk())
//설정한 output 디렉토리 하위에 index 디렉토리를 생성 후 snippets를 생성.andDo(document("index"));
}
made by jylee 20
REST Docs 시작하기 – 프로젝트 빌드
1. Target/generated-snippets/ 하위 루트에
작성한 MockMVC에서 작성한 document의 파라미터 확인
.andDo(document("index"));
made by jylee 21
REST Docs 시작하기 – asciidoc 작성
1. Src/main/asciidoc 하위 폴더에 api-guide.adoc 생성
2. Asciidoc 레퍼런스 문서를 참고하여 작성
- http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/
3. 생성된 Target/generated-snippets/ 하위 루트의 내용을 include
4. 프로젝트 재 시작 후 http://localhost:8080/docs/api-guide.html URL 실행
==== 응답 예제
include::{snippets}/index/http-response.adoc[]
made by jylee 22
참고 사이트
http://millky.com/@origoni/post/1155?language=ko_krhttp://kimseunghyun76.tistory.com/389http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/http://www.slideshare.net/OrdinaORAJ/spring-rest-docs-documenting-restful-apis-using-your-tests-devoxx
top related