REST API 문서 자동화
Spring REST Docs
안녕하세요:)
카카오헤어샵 백엔드 개발자 ian입니다!
이번 주제는 REST API 문서 자동화입니다.
현재 카카오헤어샵 백엔드에서는 Swagger를 이용해 API를 가이드하고 있습니다.
Swagger-UI그러나, Swagger가 제품 코드에 많은 어노테이션이 필요하고, API에 대한 상세 정보를 담지 못한다는 점에서 다른 자동화 방법을 조사했습니다.
Spring REST Docs 사용
Spring REST Docs 공식 사이트(아래)에서는 최소한의 노력으로 정확하고, 구조화된 문서를 생성할 수 있으며, Swagger의 제한된 방식에서 벗어날 수 있다고 말합니다.
최소한의 노력!, 그리고 자유자재로 API에 대한 설명이 가능하다는 점을 믿고, 카카오헤어샵에서 주로 다루는 매장, 디자이너에 대한 샘플 API로 프로젝트를 구성해보았습니다.
1. build.gradle 구성
- 20라인: 프로젝트 test 시 asciidoctor 동작 설정
- 46라인: build 시 생성된 문서 복사
- 동작 순서
1) 테스트케이스 수행
2) 테스트 케이스 별 /build-generated-snippets에 adoc 파일 생성됨
3) src/docs/asciidoc/ 하위의 adoc 파일에 2번에서 생성된 adoc include 하여 하나의 문서 형태로 편집됨
4) 3번에서 정의된 adoc 파일은 빌드 시점에 Assidotor Task로 /build/asciidoc/html5에 html 형태로 생성됨
5) /build/asccidoc/html5 경로의 파일을 spring boot 동작 시점에 확인할 수 있도록 src/main/resources/static/docs에 복사
2. 테스트 구성
- 14라인: id에 대한 example 속성 추가
- 17라인: branchName에 대한 optional 속성 추가
- 자동화로 문서에 표현하고 싶은 속성 값이 필요한 경우, key value로 추가 가능
(3번의 커스텀 snippet에 속성 추가 필요)
- eample 속성 값 추가 방법
3. 커스텀 snippet 추가
(src/test/resources/org/springframework/restdocs/templates 하위에 생성)
- 위의 test에서 속성으로 제공한 example, optional가 포함되도록 커스텀
- 8라인: optional 속성에 따라 필수 여부 값 생성
- 10라인: example 속성에 따라 예시 값 생성
4. 통합 AsciiDoc 파일 생성
(src/docs/asciidoc/index.adoc)
5. API 문서 추출
전체 소스코드는 아래에 있습니다.
https://github.com/ian-jo/spring-rest-docs-study
Spring REST Docs 사용 후기
1. 실제 동작과 문서가 일치
- 테스트를 기반으로 작성되기 때문에 API가 잘못되었을 경우 문서가 생성되지 않아, 문서와 코드의 불일치를 막을 수 있다는 점이 가장 큰 장점으로 생각됨
2. 테스트 코드 작성을 강제화 함
- 테스트 코드 작성이 익숙하지 않은 상태에서는 어렵겠지만, 강제적으로 작성을 유도하며 단위 테스트 주도하에 설계, 개발을 진행할 수 있음
3. 제품 코드에 영향 없음
- Swagger의 경우 제품 코드에 많은 어노테이션이 들어가는 단점이 있지만, Spring REST Docs는 제품 코드에 관련 코드가 필요하지 않아서 깔끔함
4. 문서의 커스텀 화
- 템플릿 파일 수정으로 개발자에 입맛에 따라 상세 가이드와 커스텀이 가능하여, API 정의와 이해에 큰 도움이 될 것으로 생각됨
5. API 테스트 화면 제공하지 않음
- 테스트 화면을 제공하지 않기 때문에, 동작을 확인하는 용도에서는 기존의 Swagger에 비해 편리하지 않다고 느낌
6. AsciiDoc 또는 Markdown에 대한 배경지식이 있어야 좀 더 자유롭게 사용이 가능하다고 느낌
