카테고리 없음

2023/01/09 TIL | API 문서화 (2)

또리머 2023. 1. 9. 20:06
반응형

💭 오늘의 학습 전략

# Spring Rest Docs에서의 Asciidoc

◻️ Asciidoc

　◽문법

　◽Asciidoctor

# API 문서화 실습

🌼 학습한 것들

◾ Asciidoc

　▪️ Spring Rest Docs를 통해 생성되는 텍스트 기반 문서 포맷

　▪️ html, pdf 등 다양한 형식으로 변환 가능

　▪️ 기술 문서 작성을 위해 설계된 가며운 마크업 언어이기도

　▪️ 문법

　　- 목차 구성하기

　　  = 제목. =, ==, === ...

　　  :toc: 목차 위치 설정 (:toc-title: 문서 제목, :toc-levle: 목차 제목(=) 레벨 ...)

　　  :source-highlighter:

　　  실습하면서는 :hardbreaks:를 알았다. >엔터 자동 개행

　　- 박스 문단

　　  *** 수평선

　　  제목 쓰고 한 칸 띄우고 들여쓰기 -> 박스 문단

　　- 주의사항, 참고사항 등

궁금해서 실습에 적용해봤다.

　　- URL Scheme 자동 인식

　　  http(s), ftp, 메일 주소 등은 자동 인식이 돼서 링크 설정

　　- 이미지 추가

　　  img :: 경로

◾ Asciidoctor

　▪️ asciidoc 포맷의 문서를 파싱해서 html, pdf 등 문서를 생성하는 툴

　▪️ Spring rest docs에서는 html로 변환하기 위해 내부적으로 asciidoctor 사용

　▪️ Spring rest docs를 통해 생성되는 문서 스니핏을 하나의 문서로 통합하기

== MemberController
=== 회원 상세 정보 조회
~
.response-fields	>> '.' : 하나의 스니핏 섹션 제목 표현
include::{snippets}/get-member/response-fields.adoc[]
~

=== 전체 회원 조회
~
.response-fields
include::{snippets}/get-members/response-fields.adoc[]
~

이렇게 작성하면 아래와 같이 문서가 생성된다.

path, type, description 등은 테스트 코드에서 (document())에 작성한 대로 생성된다

 

💨 하루를 마치며

1. 실습 후기

mockito 실습에 비하면 수월하게 진행되어서 좋았다. 금요일에 궁금했던 쿼리 스트링도 실습을 통해서 새롭게 알 수 있었다.(requestParameters) 어느 정도 학습 자료를 찾아보고 조금씩.....??? 테스트 코드에 익숙해지고 있는 것 같긴 하다.

회원 상세 정보 구현 문서화를 진행하다가 아래와 같은 에러도 마주쳤다.

java.lang.IllegalArgumentException: urlTemplate not found. 
If you are using MockMvc did you use RestDocumentationRequestBuilders to build the request?
 at org.springframework.util.Assert.notNull(Assert.java:201)
To make the path parameters available for documentation, the request must be built using one of the methods on RestDocumentationRequestBuilders rather than MockMvcRequestBuilders.

pathParameters 사용 시에는 MockMvcRequestBuilders보다 RestDocumentationRequestBuilders를 이용해야 한다고 한다.

import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
 -> import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;

그리고! 파라미터로 URI 객체를 넣어줬는데 String uri로 넣어주어야 했다.+ 이는 Spring Rest Docs 내부 오류라고...

 

2. asciidoc 문법은 마크다운처럼 (#, ## 이렇게) 써서 비슷하다 했던 부분도 있지만 :toc:처럼 생전 처음 보는 문법도 있었다.

3. 운동을 재미있게 하고 싶어서 새벽 수영을 시작했는데 너무너무 재미있지만 일찍 자야 해서 평소와 다르게 평일 저녁 시간을 잘 이용하지 못한다. 그 대신에 수영 마치고 집에 와서 수업 시작 전까지 약 한 시간 반 정도 시간이 생긴다. 그 시간을 어떻게 하면 좀 잘 사용할 수 있을지, 그리고 바뀐 패턴에 맞춰서 어떻게 다시 공부를 해야할 지 생각을 좀 해봐야겠따...

반응형