API 문서란

API 동작과 사용 방법을 명확하게 설명하는 문서로 개발자 간의 원활한 커뮤니케이션 도구로 쓰인다.

API 문서화의 장점

• API 소비자의 이해를 돕고 개발 중 오류를 방지
• 개발 프로세스 전반에서 효율성 및 품질 향상

Spring Rest Docs

Spring에서 API 문서화를 자동으로 해주는 도구이다.
API 동작을 테스트하면서 테스트 코드 기반으로 RESTful 문서를 자동으로 생성해준다.

설정 방법

gradle

plugins { 
	id "org.asciidoctor.jvm.convert" version "3.3.2"
}

configurations {
	asciidoctorExt 
}

dependencies {
	asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor:{project-version}' 
	testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc:{project-version}' 
}

ext { 
	snippetsDir = file('build/generated-snippets')
}

test { 
	outputs.dir snippetsDir
}

asciidoctor { 
	inputs.dir snippetsDir 
	configurations 'asciidoctorExt' 
	dependsOn test 
}

Swagger

Spring Rest Docs와 마찬가지로 API 문서화를 자동으로 해주는 도구이다.

또한 API 테스트를 편리하게할 수 있는 UI또한 제공해준다.

• 개발한 Rest API를 편리하게 문서화
• 편리하게 API 호출을 및 테스트 가능
• 백엔드와 프론트 개발자를 이어주는 다리역할

사용 방법

org.springdoc:springdoc-openapi-starter-webmvc-ui 의존성 추가

http://localhost:8080/swagger-ui/index.html 접속

Swagger VS Spring Rest Docs

• Swagger
  • 특징
    • 실시간 API 테스트 지원
    • UI를 통해 API를 쉽게 탐색 호출 가능
  • 사용 환경
    • 문서의 정확성과 코드 동기화가 중요할 때 사용
    • TDD 환경에서
• Spring Rest Docs
  • 특징
    • 테스트와 문서화를 통합 및 문서생성
    • 코드 기반 문서화로 API 스펙 상세 표현
    • 주석과 테스트 코드로 코드 동기화 유지
  • 사용 환경
    • 빠르게 상호작용하는 문서가 필요할 때
    • API를 소비하는 외부 개발자와의 협업 시 유용