RestDocs 문서화 plugin 추가 - 오류 해결

AsciiDoctor

구현한 프로젝트 api를 RestDocs를 사용해서 문서화시켜보았다.

asciidoctor 플러그인을 사용하여 문서화를 시키려고 했는데, 강사님 코드대로 pom.xml의 <plugins>에 아래 plugin을 추가하였는데도

• org.asciidoctor를 불러오지 못한다
• restdoc api의 버전을 찾지 못한다
  라는 등의 에러가 떴다.
  정확한 에러 메세지 캡쳐를 못 해놨다...

  <!-- <plugins>에 코드 추가한 부분 -->
  <plugin>
     <groupId>org.asciidoctor</groupId>
     <artifactId>asciidoctor-maven-plugin</artifactId>
     <executions>
         <execution>
             <id>generate-docs</id>
             <phase>prepare-package</phase>
             <goals>
                 <!-- docs/asciidoc/index.adoc 참고해서 target/generated-docs/html파일 생성 -->
                 <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>${spring-restdocs.version}</version>
         </dependency>
     </dependencies>
  </plugin>

해결 방법

우선 다른 교육생 분들의 해결방법이다. 나는 이 방식들대로 하여도 해결되지 않았다.

1. maven repository를 업데이트

• 먼저 IntelliJ의 Heap Size를 2G 이상 넉넉하게 늘려준다.
  • 참고: [Intellij] memory option 최적화 방법, IntelliJ Memory Option 최적화
• Settings - Build - Build Tools - Maven - Repositories 의URL을 클릭해서 Update한다
  
• 이 업데이트 방법은 heap size를 4G로 해주었는데도, 업데이트 시간이 심각하게 오래 걸려서(한참 동안 진행률이 0%길래 내 노트북이 잘못된줄 알았다..) 포기했다.

2. asciidoctor plugin의 dependency 부분 코드를 <dependencies>에도 추가

<dependency>
    <groupId>org.springframework.restdocs</groupId>
    <artifactId>spring-restdocs-asciidoctor</artifactId>
    <version>${spring-restdocs.version}</version>
</dependency>

역시나 되지 않음

3. 위에 추가했던 plugin을 삭제하고 아래 plugin 추가

   <plugin>
       <groupId>org.asciidoctor</groupId>
       <artifactId>asciidoctor-maven-plugin</artifactId>
       <executions>
           <execution>
               <id>asciidoc-to-html</id>
               <phase>generate-resources</phase>
               <goals>
                   <goal>process-asciidoc</goal>
               </goals>
           </execution>
       </executions>
   </plugin>

내가 해결한 방법

1. IntelliJ Settings - Plugins에서 install AsciiDoc
2. <dependencies>에 asciidoctor-maven-plugin dependency 추가

   <dependency>
       <groupId>org.asciidoctor</groupId>
       <artifactId>asciidoctor-maven-plugin</artifactId>
       <version>2.2.1</version>
   </dependency>

---

rest documentation은 어떻게 쓰일까?

: build와 엮어서 plugin을 실행해서 api 명세 html 파일을 만든 후, static resource를 serving할 수 있는 곳에 올리고(nginx) 공유한다.

• 항상 api 명세와

RestDocs 장점

1. Controller layer까지 test 코드를 작성할 수 있다.
   • api가 정상 동작하는지 살펴볼 수 있다.
2. 문서와 API 상태를 항상 일치시켜준다.
   • 요청/응답에서 필요한 필드와 문서의 최신 상태가 맞지 않다면 SnippetException: The following parts of the payload were not documented 에러가 뜬다.

---

최종 pom.xml 코드

https://github.com/Jummi10/kdt-jpa/blob/master/pom.xml

참고

• RESTAPI - Spring - REST DOCS 문서 빌드하기

vs Swagger

https://velog.io/@jummi10/Swagger