2023/01/06 TIL | API 문서화 (1)

💭 오늘의 학습 전략

# API 문서화

◼️ 필요성

◼️ Spring Rest Docs vs Swagger

# Spring Rest Docs

◻️ API 문서 생성 흐름

◻️ 기본 설정

　◽build.gradle

　◽src/docs/asciidoc/index.adoc

◻️ 적용해보기

🌼 학습한 것들

◾ Spring Rest Docs_API 문서 생성 흐름

◾ Spring Rest Docs_설정

　▪️  build.gradle

　　- plugins > asciidoctor 플러그인 추가

　　- ext > 스니핏 저장 경로 설정

　　- configurations > asciidoctor에서 사용되는 의존 그룹 지정

　　- dependencies 추가

　　- task 별 설정 (기능 사용을 위한 extentions, index.html 복사 경로 등)

　　- build > 빌드 전 수행될 task 설정

　　- bootJar > 애플리케이션 실행 파일이 생성하는 :bootJar task 설정

　　  (asciidoctor 실행으로 생성되는 index.html을 jar 파일에 추가 -> 브라우저 확인용)

　▪️  API 문서 스니핏을 사용하기 위한 템플릿 생성

　　- 생성된 스니핏을 최종 API로 만들어주는 템플릿 문서(index.adoc)

　▪️  적용 실습

　　- @WebMvcTest

　　- @MockBean(JpaMetamodelMappingContext.class)

　　  : @EnableJpaAuditing -> JPA 관련 Bean(JpaMetamodelMappingContext) 필요 -> WebMvcTest 사용 시 주입

　　- @AutoConfigureRestDocs

　　- andDo: 검증 작업이 아닌 일반 동작 정의

　　- document: API 문서 생성 핵심 메서드

　　  : controller 스펙에 맞춰서 requestFields, responseFields, responseHeaders 등 알맞게 작성

　　  : ignored(), optional() 등 api 스펙 정보에서 제외하거나 옵션값으로도 설정 가능 

 

🔥 보충이 필요한 것들

◾ @EnableJpaAuditing

◾ document 작성 시 쿼리 스트링은?

 

 

💨 하루를 마치며

1. Swagger를 쓰면 확실히 애너테이션이 너무 많아서 문서화 애너테이션인지 아닌지 나조차도 헷갈릴 때가 많긴 했는데 컨트롤러 테스트 케이스를 다 작성해줘야 한다니 스웨거가 더 편하게 느껴진다ㅎㅎ;;;

2. 그래도 테스트 코드는 중요하니까...

3. 그래도...

4. 😵‍💫