원글 페이지 : 바로가기
협업 프로젝트에 들어가면서 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/