# RestDocs

16개의 포스트
post-thumbnail

RestDocs로 API 문서화하기

사건의 발단 3차 스프린트를 진행하기 하루 전날 프론트가 배포되었다. 그런데 배포된 사이트에 들어가보니 반려 식물의 타임라인을 보는 페이지가 404를 띄우고있었다. 당황하지 않고 침착하게 f12를 눌러 개발자도구를 열고 네트워크탭을 확인해보니 API가 이상하게 호출되고있었다. 평소 프론트분들을 굉장히 신뢰하던 주노는 설마 하는 마음에 Notion을 열어봤다. 아니나다를까 Notion에 API 명세가 이상하게 작성되어있었다. 범인은 바로 이것저것 끄적이다가 되돌리기를 하지 않은 주노... ![](https://vel

2023년 8월 20일
·
0개의 댓글
·

[Rest Docs] @AuthenticationPrincipal로 사용으로 인한 data null 오류

Rest Docs를 처음 접했기 때문에 무한 구글링과 rest docs 원서를 읽으면서 열심히(?) 테스트 코드를 바탕으로 API 명세서를 만들고 있었다. 잘 만들던 중 모든 파라미터와 요청응답을 맞게 설정했음에도 불구하고 응답 data 부분이 null로 뜨는 에러를 만났다.! 그럼 이제 어떻게 오류를 접했고, 어떻게 해결했는지에 대해 말해보겠다. 우선 나는 회원이 좋아요 한 상품을 조회하는 로직을 작성중이었다. 그에따라 컨트롤러를 아래와 같이 작성했다. @AuthenticationPrincipal을 이용하여 userId를 받아와서 서비스 로직으로 전달했다. 그리고 test code를 작성했다. 위의 코드를 보면, 응답도 알맞게 설정하고, 요청 헤더 형식 등 모두 알맞게 구성했다. 하지만 이 코드를 run하게 되면, 아래와 같이 data:[] 과 같은 아름다운(?) 데이터 증발 현상을 만나게 된다. ㅎㅎㅎ,,,,, 삽질을 며칠동안 하면서, 롤모델(대학 동기

2023년 7월 31일
·
2개의 댓글
·

2023.02.21.TUE

[ Pre-Project ] 오늘 팀원들이랑 RestDocs API 완성했다,,! 내일 프론트 분들 감동의 눈물 흘리시길 바라며,, ㅎ0ㅎ git pull request 후, merge할 때, web에서 conflict 해결하기에는 너무 복잡하므로, 로컬에서 pull해서 충돌 다 해결한 후에 다시 push 하라는 내용이 있었다. 처음에는 당황하고 복잡했지만, 2번 해봤더니 조금 익숙해진 것 같다. local에서 remote로 push할 때, branch 이름 같아야 함. ![](https://velog.velcdn.

2023년 2월 21일
·
0개의 댓글
·

2023.02.04.SAT

[ restDocs ] jsonPath는 루트부터 property 경로 지정해줘야하고, fieldWithPath는 루트부터 경로 지정하면 restDocs 문서 만들기 실패한다고 에러남;; 한참 헤매다가 혹시?해서 바꿨더니 해결됐다. src/docs/asciidocs 경로 안에 index.adoc 파일을 만들어서 거기에서 snippet을 합쳐서 하나의 html의 베이스를 만든다. -> build하면 html 생성됨. snippet 오버라이드를 통해 custom snippet 만들기 src/test/resources/org/springframework/restdocs/templates/asciidoctor 경로에(없으면 만들어서) 커스텀을 원하는 스니핏 파일을 작성하여 오버라이드. ![](https://velog.velcdn.com/images/youngrong/post/017644fa-2842-4b

2023년 2월 4일
·
0개의 댓글
·

2023.02.03.FRI

Cloud 배포 자동화 파이프라인 : 배포 과정(Source-Build-Deploy 등 여러 과정 조합 가능) 실습에서 배포 자동화에 사용한 AWS 서비스 : CodeBuild, CodeDeploy, CodePipeline 등 배포 자동화 실습 과정 EC2 인스턴스에 JAVA, AWS CLI, CodeDeploy Agent 설치 EC2 인스턴스의 태그 설정 확인 IAM 역할을 통해, 현재 연결된 권한 및 역할 설정 및 확인 신뢰 관계 편집을 통해 역할 명시 어플리케이션에 appspec.yml, buildspec.yml, initialize.sh, serverclear.sh, serverstart.sh, server_stop.sh 파일들을 생성 및 설정 CodeDeploy에서 어플리케이션 생성 파이프라인 생성(소스-빌드-배포) 배포

2023년 2월 3일
·
0개의 댓글
·
post-thumbnail

study 02

HTTP API란? HTTP를 사용하여 프로그램끼리 소통하는 API를 말한다. 보통 우리가 흔히 보는 OPEN API, facebook API, kakao API 등의 대부분 API는 HTTP라는 통신 규칙으로 소통하는 API이다. 🔎 HTTP를 사용하지 않는 API도 있나? 미세먼지 측정기에서 미세먼지 농도 값을 읽어와서 공기가 안 좋으면, 자동으로 창문을 개방하는 IoT어플리케이션을 개발하고 싶다고 하자. 미세먼지 측정기와 스마트 창문이 IoT 애플리케이션과 통신(소통)할 수 있는 API가 있어야 한다. 이때 사용하는 소통 방법은 HTTP통신이 아닌 저사양/저전력 환경에 적합한 MQTT, CoAP프로콜을 사용해야 한다. @RestController를 하기전에 REST에 대해

2023년 1월 4일
·
0개의 댓글
·
post-thumbnail

[Spring] Spring Rest Docs 사용법

Spring Rest Docs 란? Spring Rest Docs는 Spring MVC를 사용하는 REST API를 문서화하는데 도움을 주는 프로젝트 이다. Spring Rest Docs는 Spring MVC의 테스트를 실행하면서 생성된 응답을 기반으로 문서를 생성합니다. Spring Rest Docs는 Asciidoctor를 사용하여 문서를 생성합니다. 스프링 프로젝트 팀에서는 Swagger 보다 Asciidoctor를 사용하는 것을 권장하고 있다. Why Spring Rest Docs? 이전에는 Swagger를 많이 사용했다고 한다. 물론 Swagger 의 장점은 많다. 그러나 Swagger는 Spring MVC의 테스트를 실행하지 않고 문서를 생성하기 때문에 실제로 API가 동작하는지 확인할 수 없다. Swagger는 API의 스펙을 정의하는 것이 목적이지만 Spring Rest Docs는 API의 스펙을 정의하고 테스트하는 것이 목적

2022년 11월 14일
·
0개의 댓글
·

Spring RestDocs

Spring Rest Docs 적용 Spring Rest Docs API 문서 생성 흐름 스니핏은 코드의 일부 조각을 의미하며 여기서는 문서의 일부 조각을 의미한다. 테스트 케이스 하나당 하나의 스니핏이 생성되며, 여러개의 스니핏을 모아 하나의 API 문서를 생성할 수 있다. Spring RestDocs 설정 build.gradle 설정 API 문서 스니핏을 사용하기 위한 템플릿 API 문서 생성 src/docs/asciidoc/ 디렉토리 내에 비어있는 템플릿 문서 `i

2022년 10월 9일
·
0개의 댓글
·
post-thumbnail

SpringBoot + Restdocs

원활한 업무 진행을 위해 정리해두려는 글입니다. 참고 Spring 공식 문서 Creating API Documentation with Restdocs 📗 RestDocs 설정 restdocs의 개념은 대충 알고 있으니 바로 시작하자. 📄 gradle gradle 설정을 다음과 같이 적용했다. 📄 테스트 코드 작성하기 반환할 형식의 데이터에 맞게 다음과 같이 작성해준다. 📄 adoc 작성 adoc 파일은 위 gradle에서 설정한 /src/docs/asciidoc/index.adoc파일로 작성했다. 📄 실행해보기 ./gradlew clean build를 통해 테스트 코드가 모두 실행되면 > 그냥 테스트 코드만 실행해도 되지만 build 시에 파일이 나온다는 것을 보여주기 위해! ![](https://v

2022년 8월 22일
·
0개의 댓글
·
post-thumbnail

[속닥속닥] 🚀 우당탕탕 Spring REST Docs 적용기

해당 글은 속닥속닥 기술블로그에 작성된 글과 동일합니다. > 속닥속닥 링크 0. intro 저희 속닥속닥 팀은 기존엔 API 명세를 notion을 통해 작성했습니다. 하지만 실제 코드와 연동되지 않는 점이 불편했고, API별 테스트를 통한 검증을 하고 싶었습니다. 이에 신뢰성있는 API 문서를 프론트엔드에 공유할 수 있는 REST Docs를 사용하기로 했습니다. 다음은 REST Docs 를 세팅하고 문서화 한 과정입니다. 1. build.gradle > Gradle 7.4.1 버전 > > grovvy 문법을 정확히 알지 못해 틀린 부분이 있을 수 있습니다. > 1-1. 빌드 과정 테스트 실행 테스트 결과를 build/generated-snippets에 저장 이전 `static/i

2022년 8월 7일
·
0개의 댓글
·
post-thumbnail

REST Docs "어딜 보시는 거죠? 그건 제 잔상입니다만?"

많은 프로젝트 팀들이 API 문서화를 위해 Spring REST Docs를 사용합니다. 그리고 REST Docs를 만드는 과정에서 생긴 html 파일을 서버에 함께 배포해서 사용합니다. 저희 F12팀 역시 http://{백엔드ip}:{백엔드포트}로 접속하면 docs가 뜨도록, 즉 index.html(스프링부트의 기본 설정이니까요)로 REST Docs가 뜨도록 설정하고 싶었습니다. 그렇게 하기 위해 build.gradle에 copyDocument라는 task를 작성해주었습니다. 자세히 설명하자면, 테스트 진행 이후 asciidoctor가 REST Docs를 만드는 작업을 진행하고, 작업이 끝나면 그 결과물로 나오는 index.html을 src/main/resources/static 디렉토리로 복사해서 스프링을 띄우면 기본 페이지로 REST Docs를 보여줄 수 있도록 설정하는 스크립트입니다. 그런데 실제 배포를 해보니, REST Docs가 뜨지 않았습

2022년 7월 29일
·
2개의 댓글
·
post-thumbnail

Spring REST Docs 적용 및 최적화 하기

모든 코드는 Github에 있기 때문에 함께 보시면 더 이해하기 쉬우실 것 같습니다. (공부한 내용을 정리하는 Github와 이 모든 내용을 담고 있는 블로그가 있습니다.) 1. REST Docs 란? 테스트 코드 기반으로 Restful API 문서를 돕는 도구입니다. Asciidoctor를 이용해서 HTML 등등 다양한 포맷으로 문서를 자동으로 출력할 수 있습니다. RestDocs의 가장 큰 장점은 테스트 코드 기반으로 문서를 작성한다는 점입니다. A

2022년 6월 17일
·
2개의 댓글
·

트러블슈팅 : restDocs

🚀 PathVariable이 먹지 않았던 문제 > 🚀 문서에 굳이 넣고 싶지 않은 이들이 있다면 > 🚀 field 아닌 parameter일 때 고생한 것

2022년 4월 11일
·
0개의 댓글
·
post-thumbnail

[Spring] Spring Rest Docs

1. Spring Rest Docs 란? Spring Rest Docs는 RESTful 서비스에 대한 정확하고 알기 쉬운 문서를 생성하는 것을 돕는 툴이다.즉, API 문서 작성 자동화 툴이다. Spring Rest Docs는 테스트 코드를 기반으로 생성된 snippets와 직접 손으로 작성한 문서를 결합하여 문서화한다. Spring Rest Docs는 기본적으로 Asciidoctor를 사용하여 문서화한다.Asciidoctor는 일반 텍스트를 처리하고 필요에 맞게 스타일이 지정되어 배치된 HTML을 만든다. 필요의 경우 Markdown을 사용하여 문서를 구성할 수도 있다. Spring Rest Docs는 Spring MVC의 Test 프레임워크, Spring Webflux의 WebTestClient, Rest Assured 3로 작성된 테스트에서 생성된 snippets를 사용한다. 이러한 테스트 중심 접근 방식은 API 문서의 정확성과 신뢰성을 보장한다는 장점

2022년 1월 24일
·
0개의 댓글
·
post-thumbnail

[SpringBootTest] Spring RestDocs 작성하기

들어가면서 👋 테스트 코드를 작성하면 자연스럽게 Spring RestDocs를 스쳐지나보게 된다. Spring RestDocs를 사용하게 되면 우선 테스트는 거쳐진 코드로 생각할 수 있어 안정적인(?) 코드라 생각할 수 있다. Swagger와 다르게 직접 실행을 할 수 있는 기능은 없지만 Postman 과 같은 툴이 있으니 크게 문제가 되질 않을 것 같다. 또한, Swagger를 사용하게 되면 코드에 Annotation 이 덕지덕지 붙게 되는데 이러한 코드를 제거하는 것도 개인적으로는 좋은 거 같다. Spring RestDocs와 함께 사용하는 asciidocs 도 함께 소개하고, asciidoc build.gradle 설정 및 asciidoc 작성 방법, 로컬 서버에서 보는 방법, IDE에서 실시간으로 보는 방법 등을 작성하려 한다. 그럼 RestDocs 기본적인 세팅과 사용하면서 부딪힌 이슈들을 다루고, 새로운 기능에 대해 지속적인 업데이트를 하자ㅏ.

2021년 9월 30일
·
0개의 댓글
·

Spring Rest Docs

Spring Rest Docs란? Spring Rest Docs는 테스트 코드를 기반으로 자동으로 API 문서를 작성할 수 있게 도와주는 프레임워크입니다. 그렇기 때문에 반드시 Test가 통과되어야 문서가 작성 된다는 장점이 있습니다. > Test 통과과 전제조건이기 때문에 API Spec이 변경되거나 추가/삭제 되는 부분에 대해 항상 테스트 코드를 수정해야되고, API 문서가 최신화 될 수 있도록 해줍니다. 처음에는 마크다운이 저에게 익숙하기 때문에 마크다운으로 API 문서를 작성하려고 했지만, 설정을 하는 부분도 번잡하고, 대부분의 큰 서비스 회사에서도 asciidoc을 채택하는 것 같아서 asciidoc을 사용하여 문서를 작성하기로 했습니다. asciidoc은 마크다운과 비슷하게 html를 작성할 수 있는 언어입니다. 1. Spring Rest Docs 설정 방법 일단, 의존성 라이브러리로 JUnit, MockMvc, asciidoc을 선택하여 최소한의

2021년 4월 12일
·
1개의 댓글
·