- 시작하게 된 계기 및 다짐 😮
이번 코드스테이츠의 백엔드 엔지니어링 개발자 부트캠프
에 참여하게 되면서 현직개발자 분들의 빠른 성장을 위한 조언 중 자신만의 블로그를 이용하여 배운 것 들을 정리하는게 많은 도움이 된다 하여 시작하게 되었다.
- 학습 목표 😮
목표 | 결과 |
---|---|
API 문서화 이해 | O |
Spring Rest Docs와 Swagger의 차이점 및 사용법 이해 | O |
Spring Rest Docs를 위한 기본 설정 및 사용 방법을 이해 | O |
Spring Rest Docs를 사용해서 API 문서를 생성 및 배포 | O |
- 정리 😮
1. @ApiOperation(value=" ", notes =" ")
1. API 문서화
2. Spring Rest Docs vs Swagger
1). Swagger
2). ★Spring Rest Docs의 API 문서화
Extra
1. Spring Rest docs의 Api 문서 생성 흐름
1). 테스트 코드 작성
2). test 태스크(task) 실행
3). API 문서 스니핏(.adoc 파일) 생성
4). API 문서 생성
5). API문서를 HTML로 변환
2. Spring Rest docs 설정
0). Asciidoctor플러그인을 이용하여 Api 문서를 생성
1). build.gradle 설정
2). API 문서 스니핏을 사용하기 위한 템플릿 API 문서 생성
3). 스니핏을 사용해 최종 API 문서로 만들어주는 템플릿 문서를 생성
[예제 Code]
plugins {
id 'org.springframework.boot' version '2.7.1'
id 'io.spring.dependency-management' version '1.0.11.RELEASE'
id "org.asciidoctor.jvm.convert" version "3.3.2" // (1)
id 'java'
}
group = 'com.codestates'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '11'
repositories {
mavenCentral()
}
// (2)
ext {
set('snippetsDir', file("build/generated-snippets"))
}
// (3)
configurations {
asciidoctorExtensions
}
dependencies {
// (4)
testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
// (5)
asciidoctorExtensions 'org.springframework.restdocs:spring-restdocs-asciidoctor'
implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
implementation 'org.springframework.boot:spring-boot-starter-validation'
implementation 'org.springframework.boot:spring-boot-starter-web'
compileOnly 'org.projectlombok:lombok'
runtimeOnly 'com.h2database:h2'
annotationProcessor 'org.projectlombok:lombok'
testImplementation 'org.springframework.boot:spring-boot-starter-test'
implementation 'org.mapstruct:mapstruct:1.5.1.Final'
annotationProcessor 'org.mapstruct:mapstruct-processor:1.5.1.Final'
implementation 'org.springframework.boot:spring-boot-starter-mail'
implementation 'com.google.code.gson:gson'
}
// (6)
tasks.named('test') {
outputs.dir snippetsDir
useJUnitPlatform()
}
// (7)
tasks.named('asciidoctor') {
configurations "asciidoctorExtensions"
inputs.dir snippetsDir
dependsOn test
}
// (8)
task copyDocument(type: Copy) {
dependsOn asciidoctor // (8-1)
from file("${asciidoctor.outputDir}") // (8-2)
into file("src/main/resources/static/docs") // (8-3)
}
build {
dependsOn copyDocument // (9)
}
// (10)
bootJar {
dependsOn copyDocument // (10-1)
from ("${asciidoctor.outputDir}") { // (10-2)
into 'static/docs' // (10-3)
}
}
(1)에서는 .adoc 파일 확장자를 가지는 AsciiDoc 문서를 생성해주는 Asciidoctor를 사용하기 위한 플러그인을 추가합니다.
(2)에서는 ext 변수의 set() 메서드를 이용해서 API 문서 스니핏이 생성될 경로를 지정합니다.
(3)에서는 AsciiDoctor에서 사용되는 의존 그룹을 지정하고 있습니다. :asciidoctor task가 실행되면 내부적으로 (3)에서 지정한 ‘asciidoctorExtensions’라는 그룹을 지정합니다.
(4)에서 'org.springframework.restdocs:spring-restdocs-mockmvc'를 추가함으로써 spring-restdocs-core와 spring-restdocs-mockmvc 의존 라이브러리가 추가됩니다.
(5)에서 spring-restdocs-asciidoctor 의존 라이브러리를 추가합니다. (3)에서 지정한 asciidoctorExtensions 그룹에 의존 라이브러리가 포함이 됩니다.
(6)에서는 :test task 실행 시, API 문서 생성 스니핏 디렉토리 경로를 설정합니다.
(7)에서는 :asciidoctor task 실행 시, Asciidoctor 기능을 사용하기 위해 :asciidoctor task에 asciidoctorExtensions 을 설정합니다.
(8)은 :build task 실행 전에 실행되는 task입니다. :copyDocument task가 수행되면 index.html 파일이 src/main/resources/static/docs 에 copy 되며, copy된 index.html 파일은 API 문서를 파일 형태로 외부에 제공하기 위한 용도로 사용할 수 있습니다.
(8-1)에서는 :asciidoctor task가 실행된 후에 task가 실행 되도록 의존성을 설정합니다.
(8-2)에서는 "build/docs/asciidoc/" 경로에 생성되는 index.html을 copy한 후,
(8-3)의 "src/main/resources/static/docs" 경로로 index.html을 추가해 줍니다.
(9)에서는 :build task가 실행되기 전에 :copyDocument task가 먼저 수행 되도록 합니다.
(10)에서는 애플리케이션 실행 파일이 생성하는 :bootJar task 설정입니다.
(10-1)에서는 :bootJar task 실행 전에 :copyDocument task가 실행 되도록 의존성을 설정합니다.
(10-2)에서는 Asciidoctor 실행으로 생성되는 index.html 파일을 jar 파일 안에 추가해 줍니다.
jar 파일에 index.html을 추가해 줌으로써 웹 브라우저에서 접속(http://localhost:8080/docs/index.html) 후, API 문서를 확인할 수 있습니다.
Extra
1. 애너테이션
@WebMvcTest(MemberController.class)
@MockBean(JpaMetamodelMappingContext.class)
@AutoConfigureRestDocs
2. API 문서 생성을 위한 슬라이스 테스트 작성
.andDo(document())
document(...)
1). 첫 파라미터
2). preprocessRequest(prettyPrint())/preprocessResponse(prettyPrint())
3). requestFileds(...)
4). reponseFields(...)
5). ignore()
6). optional()
7). pathParameters(....)
Extra
인터페이스
1) default 메서드
2). static 메서드
Spring Rest Docs
1. API 문서 템플릿 생성을 위한 디렉토리 및 문서 생성
API 문서 스니핏을 이용하여 제대로된 문서를 만들기 위해서 스니핏을 포함하는 템플릿 문서가 필요
템플릿 문서 내용 추가
Extra
==========================================================
1. Asciidoc
1). 목차구성
[예제Code]
= 커피 주문 애플리케이션 // (1)
:sectnums: // (2)
:toc: left // (3)
:toclevels: 4 // (4)
:toc-title: Table of Contents // (5)
:source-highlighter: prettify // (6)
(1) 문서의 제목을 작성하기 위해서는 =를 추가 (====와 같이 =의 개수가 늘어날 수록 글자는 작아짐)
(2) 목차에서 각 섹션에 넘버링을 해주기 위해 :sectnums: 를 추가
(3) :toc: 는 목차를 문서의 어느 위치에 구성할 것인지를 설정 (왼쪽에 목차가 표시되도록 left)
(4) :toclevels: 은 목차에 표시할 제목의 level을 지정 . (level의 수만큼 ==== 포함지정)
(5) :toc-title: 은 목차의 제목을 지정
(6) :source-highlighter: 문서에 표시되는 소스 코드 하일라이터를 지정
(7) *** 를 추가하면 문단을 나눠주는 수평선이 추가됨
(8) NOTE:, TIP:, IMPORTANT:, WARNING: 과 같이 문구 추가가능
2). 문서 스니핏을 템플릿 문서에 포함
[예제 Code]
== MemberController
=== 회원 등록
.curl-request // (1)
include::{snippets}/post-member/http-request.adoc[] // (2)
.request-fields
include::{snippets}/post-member/request-fields.adoc[]
.http-response
include::{snippets}/post-member/http-response.adoc[]
...
(1) .curl-request의 .은 하나의 스니핏 섹션 제목을 표현하고, curl-request는 섹션의 제목이다(직접지정).
(2) include는 Asciidoctor의 매크로 중 하나고 ::를 통하여 사용,
{sinippets}는 해당 스니핏이 생성되는 default경로를 의미하며 build.gradle에서 설정한 sinppertsDir를 참조
3). URL Scheme 자동인식
2. Asciidortor란
- 피드백 😮
Spring 에서 Rest Docs를 이용하여 문서화를 작업하는 과정을 학습하였다.
Swagger의 경우, 코드 @Apixxx 처럼 어노테이션을 활용하여 코드에 작성하는 방법이지만, 보기가 어렵고 복잡하여 잘 사용하지 않는다.
*Rest Docs의 경우, 각 Controller의 테스트 케이스에 대하여 request body와 response body를 이용하여 작성하고, Asciidoc라이브러리를 이용하여 작성한다.
- 앞으로 해야 될 것 😮