1. plugin 추가
id "org.asciidoctor.jvm.convert" version "3.3.2"
2. 라이브러리 추가
testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
3. tasks.named 삭제
4. 테스트 후 snippetsDir 변수에 담긴 폴더에 저장할거임
아직 build라는 폴더 없음!
테스트 후 결과를 담는다
이것도 grooby 언어임
ext {
snippetsDir = file('build/generated-snippets')
}
test {
outputs.dir snippetsDir
useJUnitPlatform()
}
asciidoctor {
dependsOn test
inputs.dir snippetsDir
}
bootJar {
dependsOn asciidoctor
copy {
// src/docs/asciidoc == from 경로
from "${asciidoctor.outputDir}"
into 'src/main/resources/static/docs' // /static/docs로 복사!
}
}
outputs.dir에 테스트 후 나오는 API 문서가 나오는데 snippetsDir로 온다.
asciidoctor는 test라는 task가 끝나면 내부가 실행될거라는 말
-> 그 전에 test 실행되는데 테스트 먼저 하고 아스키닥터가 실행됨 (RestDoc)
./gradlew build -> build 폴더 생성 -> lib 폴더 -> *.jar 파일 생성
asciidoctor의 outputDir 디폴트 경로가 src/docs/asiidoc이다.
jar 파일이 생성될 때
내 프로젝트 내부에 src/docs/asiidoc 이 폴더에 *.html 파일이 만들어진다. API 문서 결과물
얘를 into를 사용해 copy할건데 src/main/resources/static/docs로 복사한다.
내가 서버를 실행했을 때 8080으로 실행하면 static 폴더로 다이렉트하게 접근 가능하니까
최종적으로 localhost:8080/docs/*.html 하면 파일이 열리는 것이다.
5. 프로젝트 적용
어노테이션을 붙여준다, 이 정보가 API 문서에 적용된다.
@AutoConfigureRestDocs(uriScheme = "http", uriHost = "localhost", uriPort = 8080).andDo(MockMvcRestDocumentation.document("/post/api/user"))갑자기 build 폴더가 생겼다.
각각 퍼져있는 adoc 파일들을 하나의 html 문서로 만들어줄것이다.
이 귀찮은걸 restdoc이 해준다.
조건
src/docs/asciidoc/머시기.adoc을 직접 하나 만들어야한다.
그래야 html 파일이 나온다.
이거까지 자동화해주지 않는다.
이름은 내 마음대로 해도됨
이건 고정
ifndef::snippets[]
:snippets: ./build/generated-snippets
endif::[]
= REST API
:toc: left
:toclevels: 2
:source-highlighter: highlightjs
=== 1. 회원가입
===== Request Example
include::{snippets}/post/api/user/http-request.adoc[]
===== Response Example
include::{snippets}/post/api/user/http-response.adoc[]
이제 테스트하고 build해보자.
adoc 파일은 테스트할 때 생긴다.
junit이 없으면 restdoc을 사용할 수 없다.
andDo ~~ document를 붙여야 생기는 거임.
./gradlew build 하면 docs 폴더가 생성된다.
아래 api-docs.html 파일을 open with live server로 열어보자.
그냥 개쩐다
이거 설정해뒀기 때문이다.
이거 3줄만 적으면 색깔도 예쁘게 나오는 것이다.
레벨은 뭐고 뭔지 궁금하면 구글에 RestDoc :toc: left 이런거 검색해보면 됨
::이 뭔지 이건 문법인데 이건 groovy 언어 문법이다.
디폴트 경로가 src/docs/asciidoc
src/main/resources/static에 복사도 잘 되었다.
본코드 하나 작성할 때마다 테스트 코드를 작성하면
자동으로 adoc 파일이 생성된다. (html 파일은 아직 안생김!)
우리가 개발해서 배포하는건 실제로 build 폴더 내부의 jar 파일이다.
실제 실행을 해보자.
그렇다고 build 폴더가 생기지 않는다.
1. 도메인 - 레파지토리 - 레파지토리테스트
2. 서비스 - 서비스 모키토 테스트
3. 컨트롤러 - 컨트롤러 통합 테스트 + andDo ~~ document
@AutoConfigureRestDocs 붙이고!!
4. 테스트 잘됨? 문서도 보면서 하자 -> ./gradlew build -> build 폴더 생성
대신에 src/docs/ascii/asc-docs.adoc 생성해둬야함
5. 복사는 중요하지 않음 안해도됨 그냥 open with live server로 확인하면 되지
근데 dependOn은 해야함
이걸 안하면 순서가 뒤죽박죽됨
대신 복사해놓으면 localhost:8080/docs/asciidoc/api-docs.adoc으로 확인할 수 있음 서버에서
폴더 자동화 위해!
통합테스트할 때 ExtendWith(SpringExtension.class)와 SpringbootTest와 같은거고
ExtendWith({SpringExtension.class, RestDocumentationExtension.class})와
@AutoConfigureRestDocs와 같은 것이다.
아까 우리가 사용한 document 커스터마이징 할거야
/post/api/user 같은 폴더 지정하기 귀찮아서 하는거야
{class-name}/{method-name} 이니까 예를들면
user-api-controller-test/save-test 이렇게 된다.
얘들은 커멜 표기법 안쓰고 하이픈 사용한다.
그리고 밑에 두줄은 예쁘게 나오는 설정임.
mockmvc 실행될때마다 alwaysDo(document)를 걸어서 항상 실행되게.
중요한건 어떤식으로 폴더구조를 만들지만 결정하면 됨.
"hello/hihihih"라고 설정해두면 계속 이 폴더에 저장되는 것임.
동적으로 만들어야한다.
그리고 이제 AbstractControllerTest를 UserApiControllerTest에 extends해주고
@AutoConfigureMockMvc는 지워주면 된다. 부모가 갖고있으니까
MockMvc도 Autowired 할 필요없다
부모가 갖고있으니까
이제 andDo에 document만 적어주면 된다.
이렇게 하면 잘도는데 하나만 더 해주자
mockMvc에 시큐리티를 추가할 수 있다.
필요한 제이유닛 파일마다 얘만 extends하면 편하다.
시큐리티 적용하려면 시큐리티 환경을 가져와야한다.
.apply(SecurityMockMvcConfigurers.springSecurity())
일단 지금은 시큐리티 라이브러리가 없기 때문에 오류가 날 것이다.
