1. Smart-Doc 소개
- Swagger의 단점인 코드 침습성 문제를 해결하기 위해 출시된 오픈소스
- 표준 Java 주석을 스캔하여 Swagger 와 같이 API 문서를 생성하는 방식
- API 문서를 마크다운, HTML, 포스트맨 등의 다양한 형식으로 출력 지원
2. Smart-Doc 적용하기
2-1. 의존성 추가
Smart-Doc 가이드 문서 홈페이지에 접속하면 최신 버전을 뱃지로 확인할 수 있다.
<plugins>
<plugin>
<groupId>com.ly.smart-doc</groupId>
<artifactId>smart-doc-maven-plugin</artifactId>
<version>[latest version]</version>
<configuration>
<configFile>./src/main/resources/smart-doc.json</configFile>
<projectName>${project.description}</projectName>
</configuration>
</plugin>
</plugins>2-2. 설정 추가
src/main/resources/smart-doc.json 파일을 작성한다.
- outPath : 필수 값으로, 결과물이 저장될 경로를 지정한다.
- allInOne : 선택 값으로, 모든 API에 대해 생성된 문서를 하나의 파일로 확인할지에 대한 유무
- 기본 값은 false이며, 기본 값을 이용할 경우 Controller 하나당 html 파일이 하나씩 생성된다.
- 이외에도 선택할 수 있는 옵션들이 다양하니, 첨부 링크에서 확인하자.
{
"outPath": "src/main/resources/static",
"allInOne": true
}2-3. 주석 정리
Smart-Doc으로 생성되는 문서는 주석 기반이며, 기존의 Javadoc 애너테이션들이 호환된다.
예시로, 아래와 같이 작성한 API가 있다고 가정하자.
/**
* 예시 API Endpoint
*
* @author 이동엽(Dongyeop, Lee)
* @date 2024. 05. 02
* @description 예시 API Endpoint
* @history <pre>
* -----------------------------------------------------------------
* 변경일 작성자 변경내용
* --------------- ---------- --------------------------------------
* 2024. 05. 02 이동엽 최초 작성
*
*
* </pre>
*/
@Slf4j
@RestController
@RequestMapping("/api/v1/example")
@RequiredArgsConstructor
public class ExampleController {
private final ExampleService exampleService;
/**
* 협진 내용 목록 조회
*
* @param pageSize : 페이지 크기
* @param pageNum : 페이지 번호
* @param sort : 정렬 기준
* @param sortDir : 정렬 방향
* @return : 협진 요약 목록
*/
@GetMapping("/{roomId}")
public Page<DoctorConsultDetailsDto.Res> getConsultList(@PathVariable(value = "roomId") final String roomId) {
log.debug("roomId[{}]", roomId);
final Doctor doctor = AuthenticationUtils.getUser();
return exampleService.findByRoomId(doctor.getId(), roomId);
}
}2-4. Smart-Doc문서 생성
IntelliJ 사용 시
우측의 maven plugins에서 원하는 종류의 파일 형식을 더블 클릭하면 smart-doc이 형성된다.
CLI 사용 시
아래의 커맨드를 입력하면 입력한 형식의 smart-doc이 형성된다.
$ mvn -Dfile.encoding=UTF-8 smart-doc:html2-5. 문서 확인
Spring Security 설정 변경
Spring Security를 이용해 해당 경로에 접속할 수 있도록 관련 파일들에 대한 접근을 허용해야 한다.
// SecurityConfig.java
@Bean
public SecurityFilterChain securityFilterChain(final HttpSecurity http) throws Exception {
return http
.authorizeHttpRequests(request -> request
...
.requestMatchers(new AntPathRequestMatcher("/index.html"), new AntPathRequestMatcher("/AllInOne.css"), new AntPathRequestMatcher("/cont.css"), new AntPathRequestMatcher("/hilight.min.js"), new AntPathRequestMatcher("/jquery.min.js"), new AntPathRequestMatcher("/search.js"), new AntPathRequestMatcher("/xt256.min.css")).permitAll() )
.build();
}브라우저에서 문서 확인
Spring Boot 프로젝트 실행 후, 브라우저에서 {서버 주소}:{포트번호} 접속시 src/main/resources/index.html을 볼 수 있다.
3. 추가 작업
3-1. 특정 환경에서만 Smart-Doc을 생성하고 싶을 경우
API 문서의 경우에는 Production/Stage 환경에서는 보여줄 필요가 없다. (보여줘서는 안된다.)
따라서 Develop 환경에서만 보여주기 위해 아래와 같이 프로필을 dev일 때만 동작하게 플러그인을 추가한다.
<profiles>
<profile>
<id>dev</id>
<build>
<plugins>
<plugin>
<groupId>com.ly.smart-doc</groupId>
<artifactId>smart-doc-maven-plugin</artifactId>
<version>3.0.5</version>
<configuration>
<configFile>./src/main/resources/smart-doc.json</configFile>
<projectName>${project.description}</projectName>
</configuration>
</plugin>
</plugins>
</build>
</profile>
</profiles>3-2. 요청/응답 등의 템플릿 커스텀
아래와 같이 예제 데이터를 넣을 수는 있으나, 템플릿을 커스텀할 수는 없다.
{
"requestHeaders": [ //Set request headers, you don't need to set them if you don't have any requirements
{
"name": "token", //Request header name
"type": "string", //Request header type
"desc": "desc", //Request header description information
"value": "kk", //Do not set the default null
"required": false, //Is it necessary?
"since": "-", //What version added the request header?
// since 2.2.2
"pathPatterns": "/app/test/**", //Only URLs starting with /app/test/ will have this request header
"excludePathPatterns": "/app/login" // Login url=/app/page/ will not have this request header
}
]
}4. Swagger와의 비교
Smart-Doc은 Swagger의 단점을 개선해서 나온 점이기에, REST Docs와는 비교를 하지 않았습니다.
4-1. 표준 주석 Javadoc을 이용한 문서 생성 방식
개발팀의 기존 컨벤션 중에는 아래와 같은 주석을 반드시 남겨야 했습니다.
또한 Public 메서드의 경우도 Javadoc을 이용해 설명을 첨부하곤 했습니다.
→ 이러한 기존의 컨벤션을 유지한 상태로 추가한 코드는 한줄도 없이, API 문서를 생성할 수 있습니다.
/**
* @author 홍길동(Gildong, Hong)
* @date 2023. 09. 07
* @description
* @history <pre>
* -----------------------------------------------------------------
* 변경일 작성자 변경내용
* --------------- ---------- --------------------------------------
* 2023. 09. 07 홍길동 최초 작성
*
*
* </pre>
*/4-2. 다양한 출력 형식 지원
마크다운, HTML, Postman, OpenAPI, Jmeter 스크립트 등의 다양한 출력 형식을 지원하기에, 필요에 따라 API 문서의 형태를 바꿀 수가 있습니다.
-
HTML : 브라우저에서 확인 가능
-
Postman : 포스트맨에서 import 후 사용
-
Jmeter : 스크립트를 import하여 성능 테스트에 사용 가능
-
Open API : Swagger와 동일하게 요청을 Try할 수 있음
4-3. 여전히 코드 침범이라고 보이는 점들
위에서 봤던 Smart-Doc 예시를 보면, 응답 필드들이 아래와 같이 보여진다.
응답 필드들의 경우에도 설명을 작성하고 싶다면, 응답 클래스에서 각 필드별로 모든 주석을 Javadoc으로 작성해야 한다.
→ 애너테이션으로 컨트롤러 코드를 침범하지 않았을 뿐, 주석을 일일이 달아줘야 한다면 노동이 들어가는 것은 여전히 좋지 않다고 생각된다.
5. 마무리
그래도 Swagger의 애너테이션들이 컨트롤러 코드에 침범하지 않는 점과 다양한 출력 형식을 제공한여 원하는 방식으로 이용할 수 있는 장점이 Swagger보다 훨씬 매력적입니다.
따라서 필요에 따라 REST Docs와 Smart-Doc 중 적합한 것들을 선택하면 될 것 같습니다.
6. 참고자료
