예제 : https://github.com/leejuyeon/test_springRESTDocs.git spring rest doc에 대한 자료가 많이 없어 직접 만듦

1. RESTful API 문서화
Spring REST Docs
made by jylee 1
이해와 따라 하기

2. made by jylee 2
API와 API문서화
다른 서비스에 요청을 보내고 응답을 받기 위해 정의된 명세
• API
제공하는 API 서비스의 로직을 문서로 기술하는 것
• API 문서화

3. made by jylee 3
API와 API문서화

4. made by jylee 4
API문서화 툴
Wiki

5. made by jylee 5
API문서화 툴
• 주석을 통한 문서화
• 아직 테스트가 필요한 단계

6. made by jylee 6
API문서화 툴
• JSON 파싱을 통한 문서화
• Node.js 와 Redis 설치 필요

7. made by jylee 7
API문서화 툴

8. made by jylee 8
API문서화 툴
• Annotation을 사용한 문서화
• 개발 기능과 문서와의 싱크 ↑
• 그러나 복잡해지는 소스코드

9. made by jylee 9
API문서화 툴
• Annotation을 사용한 문서화
• 개발 기능과 문서와의 싱크 ↑
• 그러나 복잡해지는 소스코드

10. made by jylee 10
Spring REST Docs?
We made tool
Spring REST Docs

11. made by jylee 11
Spring REST Docs?
+
@Test
Mock Test
+

12. made by jylee 12
Spring REST Docs?
=

13. made by jylee 13
API-Guide.adoc
include
maven-resources-plugin
API-Guide.html*documentation.java
@Test
//단위테스트
document(“index”)
Snippets
Spring REST Docs!
~asciiDotor~

14. 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>

15. 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>

16. 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>

17. 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>

18. 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>

19. made by jylee 19
REST Docs 시작하기 - MockMVC
1. *documentation.java 파일을 생성
2. 단위 테스트 작성
@Test
public void test() throws Exception{
//해당 url을 실행
this.mockMvc.perform(get(＂/member/＂).accept(MediaType.APPLICATION_JSON))
//응답 성공을 가정
.andExpect(status().isOk())
//설정한 output 디렉토리 하위에 index 디렉토리를 생성 후 snippets를 생성
.andDo(document("index"));
}

20. made by jylee 20
REST Docs 시작하기 – 프로젝트 빌드
1. Target/generated-snippets/ 하위 루트에
작성한 MockMVC에서 작성한 document의 파라미터 확인
.andDo(document("index"));

21. 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[]

22. made by jylee 22
참고 사이트
http://millky.com/@origoni/post/1155?language=ko_kr
http://kimseunghyun76.tistory.com/389
http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/
http://www.slideshare.net/OrdinaORAJ/spring-rest-docs-documenting-restful-apis-using-your-tests-devoxx