[Key Word 개발기] Swagger ?? Spring Rest Docs??

협업 프로젝트에 들어가면서 api문서에 있어 Swagger를 사용할까??Spring Rest Docs를 사용할까?? 고민하였다.

나는 개인적으로는 Spring Rest Docs를 적용하고 싶었다. 그 이유를 여기서 차차 설명할것이다.

 

 

첫번째 Swagger는 운영코드에 침투적이다

 

Swagger를 사용하려면 컨트롤러단에 코드를 추가해야한다.예를 들어

 

@ApiOperation(value=" 회원 조회 ")
@ApiResponses(value = {
	@ApiResponse(code=200, message ="회원 존재", response=String.class),
        @ApiResponse(code=500, message = "서버 에러")
	}
@PostMapping("/member/{id}")
public ResponseEntity<?> findMember(@PathVariable Long id){

	.......
}

 

간단하게 코드를 만들었다.

이렇게 운영 코드에 침투적이다. 만약 코드 수정이 필요한 경우 저 swagger까지 고쳐줘야하는데.. 뭐랄까..??강제성이 없는 느낌..깜빡하고 안고칠 수 도 있는 느낌..??

 

반면 RestDocs는 운영코드에는 영향이 없다. 단지 테스트 코드에 코드가 추가되는 것 뿐..?

 

두번째 RestDocs는 테스트 코드가 강제적이다

 

나는 이 부분이 좋았다. 어처피 테스트코드를 작성해야하는 부분을 이용해서 api문서를 만들 수 있었다. 거기다가 만약 운영코드에 수정이 필요해서 수정했다면 테스트 코드를 수정하지 않는 이상 에러가 나오기때문에 깜빡쓰의 느낌이 사라진다.(테스트가 성공해야만 문서 작성이 되기 때문)

 

 

---

물론 Swagger에 편리한점도 있다. API를 테스트 해볼수 있는 화면을 제공한다는 점이다.

또한 어노테이션만 잘 붙이면 되기 때문에 적용하기가 쉽다.

뿐만 아니라 RestDocs는 asciidoc을 작성해서 api문서 뷰단?을 완성해야하지만 Swagger는 이쁘게 잘 알아서 생긴다.

 

 

근데 찾아보니 Restdocs + Swagger를 같이 사용할 수 있는 것 같다.

그걸 OpenApi Specification이라고 하는 것같다. 기본적으로 docs로 하되 문서를 swagger로 변환시켜주는 것 같다.

 

즉 테스트코드 통해 docs 문서 생성 -> 해당 문서 OpenApi로 변환 -> 해당 변환 스펙을 Swagger Ui로 생성 -> 생성된 UI를 static 패키지에 복사 및 정적 리소스로 배포

 

이부분에 대해서는 나중에 설명하고 rest docs사용법에 대해서 간단하게 설명하자

 

---

api문서에 관한 mockmvc테스트는 이 블로그를 참고하기를 바란다

https://velog.io/@hwsa1004/Spring-Spring-RestDocs-%EC%A0%81%EC%9A%A9%ED%95%98%EA%B8%B0

 

많이 도움이 되었다.

 

테스트 코드를 작성했으면 다음과정을 거치면 된다

 

1. 테스트 코드를 MockMvc로 작성한 후 테스트가 통과 되면 build/generated-snippets 하위에 문서 조각들이 생성된다

 

2.이후 생성된 스니펫들을 묶은 html문서를 만들기 우해 src/docs/asciidoc 하위에 스니펫을 묶은 adoc문서를 만든다

 

3.adoc문서를 만들었다면 

 ./gradlew asciidoctor

 

 

해주면 build>docs>asciidoc에 adoc 파일과 동일한 html 파일이 생성된다

 

4. 이후

./gradlew build

 해주면 resources - static - docs 하위에 html 문서가 생성된다

(다만 api문서 확인할때 위 처러하면 localhost:8080 등등 해서 가능하지만 AsciiDoc플로그을 설치하면 인텔리제이 상에서도 실시간으로 확인할 수 있다)

 

 

---

https://github.com/ParkHaeBeen/Spring-RestDocs-Test

 

관련하여 깃에 간단하게 테스트 코드 작성하여 레포에 올려놓았다.

아주 간단한거라서 감만 잡는 느낌으로 하고 나머지는 검색하면서 하면 좋을 것같다!

 

 

 

참고블로그

https://velog.io/@ohzzi/REST-Docs-%EC%96%B4%EB%94%9C-%EB%B3%B4%EC%8B%9C%EB%8A%94-%EA%B1%B0%EC%A3%A0-%EA%B7%B8%EA%B1%B4-%EC%A0%9C-%EC%9E%94%EC%83%81%EC%9E%85%EB%8B%88%EB%8B%A4%EB%A7%8C

https://hudi.blog/spring-rest-docs/