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