Spring Rest Docs 적용
•
정의) Java Spring 진영에서 쓰이는 API 문서 자동화 도구
◦
Swagger vs Spring Rest Docs
Swagger | Spring Rest Docs | |
장점 | - 적용이 쉬움
- API 테스트 화면 제공함 | - 제품 코드에 영향 없음
- 테스트가 성공해야 문서 작성되어 API 스펙과 항상 일치함(동기화) |
단점 | - 제품코드에 어노테이션 추가해야 함
- 제품코드와 동기화 안될 수 있음 | - 적용이 어려움 |
•
사용 기술)
◦
SpringBoot, Gradle, jUnit4, MockMvc, AsciiDoc
jUnit4 | Spock | |
장점 | - 라이브러리 추가하지 않아도 됨
- 컴파일 시점에 오류 잡기 쉬움 | - BDD 스타일로 직관적임
- 동적 테스트가 쉬움 |
단점 | - 동적 테스트 작성이 불편함 | - 라이브러리 추가해야 함
- 컴파일 시점에 오류 찾기 힘듦 |
MockMvc | RestAssured | |
장점 | - @WebMvcTest로 수행이 가능해 Controller Layer만 테스트하기에 속도가 빠름
- 문서 작성하기에 적당함 | - BDD 스타일로 직관적임
- 통합 테스트할 땐 좋은 선택이 될 수 있음 |
단점 | - 별도 구성 없이는 @SpringBootTest로 수행해야 하는데 전체 컨텍스트를 로드해 빈을 주입하게 되어 속도가 많이 느림 |
AsciiDoc | Markdown | |
장점 | - include 기능을 제공함
- 강력한 표현력 가짐 | - 개발자에게 친숙함 |
단점 | - 개발자에게 친숙하지 않음
- Ruby 의존성 때문에 빌드 시간 오래 걸림 | - import 기능 있지만 사용 불편함 (Slate 사용하면 편하다고 하지만, 결과물이 우리가 생각한 doc 파일과 다르며 별도 설정 해야 하는 번거로움이 있음)
- 단순해서 API 명세 문서화하기에 표현력 제한됨 |
◦
적용)
▪
./build.gradle
plugins {
id("com.epages.restdocs-api-spec") version "0.15.3"
}
repositories {
mavenCentral()
}
dependencies {
testImplementation("com.epages:restdocs-api-spec-mockmvc:0.15.3")
}
openapi3 {
this.setServer("https://localhost:8080") // list로 넣을 수 있어 각종 환경의 URL을 넣을 수 있음!
title = "My API"
description = "My API description"
version = "0.1.0"
format = "yaml" // or json
}
Java
복사
◦
생성)
▪
documentation / openapi3 클릭 시 /build/api-spec 디렉터리에 OAS 기본 구조가 작성된 openapi3.yaml 파일이 생성됨
▪
우리팀은 아래와 같이 커스텀해서 src/main/resources/static/docs에 생성되게 변경했음
openapi3 {
server = 'http://localhost:8080'
...
outputDirectory = 'src/main/resources/static/docs'
Java
복사
•
참고
네이버 캠퍼스 핵데이 Java 코딩 컨벤션 적용
적용 방법
•
.editorconfig 파일 추가
◦
해당 파일을 루트 디렉토리에 추가하면, 별도 설정 없이도 IDE에서 해당 파일을 인식하여 포매팅을 적용함
◦
코드 스타일 관리하는 표준 도구
# top-most EditorConfig file
root = true
[*]
# [encoding-utf8]
charset = utf-8
# [newline-lf]
end_of_line = lf
# [newline-eof]
insert_final_newline = true
[*.bat]
end_of_line = crlf
[*.java]
# [indentation-tab]
indent_style = tab
# [4-spaces-tab]
indent_size = 4
tab_width = 4
# [no-trailing-spaces]
trim_trailing_whitespace = true
[line-length-120]
max_line_length = 120
Java
복사
•
.editorconfig가 올바르게 적용되었는지 확인. 우측 하단에 4 space 버튼 클릭했을 때 아래와 같은 창이 뜨면 성공
•
•
자바 핵데이 컨벤션 문서의 Appendix D: 편집기 설정 중 D.2.4. 파일을 저장 할 때마다 포멧터 자동 적용 섹션에 있는 내용을 적용. 파일 마지막에 있는 newline을 지우고 저장 시 자동으로 다시 newline이 추가되면 성공.
•
참고
아래 PR 내용을 바탕으로 작성함
윈도우 특이사항 : 새줄 적용 관련해 git checkout 할 때마다 CRLF로 바꿔버려서 컨벤션에 맞지 않게 된다.
•
아래와 같이 설정해 해결 가능하다.
•
참고
정적 팩토리 메소드 네이밍 컨벤션
•
from : 인자 한 개일때
•
of : 인자 여러 개일때
REST API에서 연관관계
•
REST 리소스 간에는 연관 관계가 있을 수 있고, 이런 경우 다음과 같은 표현방법으로 사용
/리소스명/리소스 ID/관계가 있는 다른 리소스명
ex) GET : /users/{userid}/devices (일반적으로 소유 ‘has’의 관계를 표현할 때)
Plain Text
복사
•
만약에 관계명이 복잡하다면 이를 서브 리소스에 명시적으로 표현하는 방법이 있음.
◦
예를 들어 사용자가 ‘좋아하는’ 디바이스 목록을 표현해야 할 경우 다음과 같은 형태로 사용
GET : /users/{userid}/likes/devices (관계명이 애매하거나 구체적 표현이 필요할 때)
Plain Text
복사
RequestParam naming convention
•
camel case로 간다.
