Spring REST Docs

데이터베이스와 통신하는 방식 중에 하나로 REST 통신이 있다.

REST통신에 대해서는 아래 참고 포스팅을 확인해보면 도움이 될것이다.

 

REST 를 활용하여 api 를 만들게 된다.

그러면서 정리 문서를 만들어야 하는 때가 온다.

얼마전 포스팅에서 문서화 관련 javadoc 관련 포스팅을 작성하기도 하였고, 참고 포스팅을 확인해보도록 한다.

 

하지만 해당 javadoc 은 주석 기반으로 문서를 만들어주는것이고

오늘 소개할 REST Docs 의 특징은 아래와 같다.

• 테스트 코드 기반으로 Restful API 문서를 돕는 도구
• Asciidoctor를 이용해서 HTML 등등 다양한 포맷으로 문서를 자동으로 출력할 수 있음
• RestDocs의 가장 큰 장점은 테스트 코드 기반으로 문서를 작성하는 점
• API Spec과 문서화를 위한 테스트 코드가 일치하지 않으면 테스트 빌드를 실패하게 되어 테스트 코드로 검증된 문서를 보장할 수 있음

참고 포스팅에도 올렸는데 그래서 테스트 기반으로 문서를 작성한다는건 이전 포스팅으로 swagger 이랑 뭐가 다른가?

 

보통 Spring 에서 문서화를 할 때, Swagger과 Restdocs를 사용하게 된다.
Swagger는 마치 Postman처럼(직접 요청하듯이) API를 테스트해 볼 수 있는 화면을 제공하여 동작 테스트하는 용도에 조금 더 특화되어있고 그렇다면 Swagger는 문서화도 되고 테스트도 가능하니 더 좋은 것이 아닌가라고 생각할 수 있는데 하지만 Swagger를 사용할 경우 명확한 단점이 존재한다.

1. 로직에 애노테이션을 통해 명세를 작성하게 되는데 지속적으로 사용하게 된다면 명세를 위한 코드들이 많이 붙게되어 전체적으로 가독성이 떨어진다.
2. 테스트 기반이 아니기에 문서가 100% 정확하다고 확신할 수 없다.
3. 모든 오류에 대한 여러 가지 응답을 문서화할 수 없다.

이에 반해 REST Docs 에는 다음과 같은 장점이 있다.

1. 테스트 기반으로 문서가 작성되어 테스트 코드가 일치하지 않으면 테스트 빌드가 실패하게 되기 때문에 문서를 신뢰할 수 있다.
2. 테스트 코드에서 명세를 작성하기 때문에 비즈니스 로직의 가독성에 영향을 미치지 않는다.

---

사용법

• pom.xml 추가

<dependency>      <groupId>org.springframework.restdocs</groupId>     <artifactId>spring-restdocs-mockmvc</artifactId>     <version>{project-version}</version>     <scope>test</scope> </dependency> <build>     <plugins>         <plugin>              <groupId>org.asciidoctor</groupId>             <artifactId>asciidoctor-maven-plugin</artifactId>             <version>2.2.2</version>             <executions>                 <execution>                     <id>generate-docs</id>                    <phase>prepare-package</phase>                     <goals>                         <goal>process-asciidoc</goal>                    </goals>                     <configuration>                         <backend>html</backend>                        <doctype>book</doctype>                     </configuration>                 </execution>             </executions>             <dependencies>                 <dependency>                      <groupId>org.springframework.restdocs</groupId>                     <artifactId>spring-restdocs-asciidoctor</artifactId>                     <version>{project-version}</version>                 </dependency>             </dependencies>         </plugin>     </plugins> </build>

그리고 추가적으로 

작성된 doc을 jar에 package하기 위해 또 플러그인이 필요하다. 아래내용도 pom.xml에 추가해야한다.

<plugin>      <artifactId>maven-resources-plugin</artifactId>     <version>2.7</version>     <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>

위 내용을 추가하면 doc가 작성이 되면 static/docs밑으로 배포된다.

 

Test Code 작성

• Spring Rest Docs를 사용하기 위해서는 무조건 Test Code를 작성해야 한다.
• @ExtendWith(RestDocumentationExtension.class) 는 필수로 넣어준다.
• 공식문서를 보면 MockMvc를 @Before method 통해 설정해주었지만, 해당 프로젝트에서 uriHost 명을 설정하기 위해 @AutoConfigureRestDocs 어노테이션을 사용하였기 때문에 따로 @Before 과정이 필요 없었다.

그래서 아래 사진과 같이 테스트 코드를 작성하면된다.

json 을 사용해서 테스트 객체를 만들고 메서드와 uri 를 포함하여 몇가지 정보를 넣어주고 저장될 이름을 설정하면 된다.

그러고 나면 아래와 같이 test폴더 내에 파일이 생성이 된다.

---

참고 사이트

https://thenicesj.tistory.com/201

websocket과 Rest의 차이점

https://thenicesj.tistory.com/252

swagger-ui 사용법

https://thenicesj.tistory.com/318

javadoc 관련