Swagger란?

Swagger란 무엇인가요?

• 정의: Swagger는 REST API를 자동으로 문서화하고, 테스트할 수 있는 도구입니다. 개발자가 API 엔드포인트(예: /users, /login)를 쉽게 설명하고, 클라이언트가 API를 실시간으로 확인할 수 있도록 도와줍니다.
• 주요 특징:
  • API 문서를 자동 생성합니다. (수동으로 작성할 필요가 줄어듭니다!)
  • 인터랙티브한 UI(예: Swagger UI)를 제공해 API를 바로 테스트할 수 있습니다.
  • JSON이나 YAML 형식으로 API 명세를 작성해 공유할 수 있습니다.
• 왜 사용하나요?: 프로젝트에서 API를 여러 개발자나 팀이 사용할 때, 일관된 문서를 유지하고 실수 없이 테스트하려면 Swagger가 큰 도움이 됩니다.

Swagger 사용 방법

• 의존성 추가: build.gradle에 Swagger 관련 의존성을 추가합니다.
• 설정: Spring 부트 애플리케이션에 별도 설정 없이도 기본 경로(/swagger-ui.html)에서 Swagger UI를 확인할 수 있습니다.
• application.yml 파일에 설정 추가해 보기
• 활용: @GetMapping, @PostMapping 같은 어노테이션에 설명을 추가해 문서를 풍부하게 만들 수 있습니다.
• 결과: 브라우저에서 http://localhost:8080/swagger-ui.html에 접속하면 API 목록과 테스트 버튼이 보입니다.

Swagger vs Spring REST Docs 개념 비교

• Swagger:
  • 특징: 런타임(프로그램 실행 중)에 API 문서를 자동 생성합니다. 개발 중 실시간으로 확인 가능.
  • 장점: 설정이 간단하고, UI로 바로 테스트할 수 있어 초보자에게 적합합니다. 문서가 프로젝트와 동기화됩니다.
  • 단점: 문서가 코드에 의존적이라, 코드가 변경되면 문서도 자동 변경됩니다. (정확성 보장 필요)
  • 사용 시기: 빠르게 프로토타입을 만들거나, 팀 간 빠른 피드백이 필요한 경우.
• Spring REST Docs:
  • 특징: 테스트 코드를 기반으로 API 문서를 정적으로 생성합니다. (예: AsciiDoc 형식)
  • 장점: 테스트 결과와 문서가 일치하므로 신뢰성이 높습니다. 커스터마이징이 자유롭습니다.
  • 단점: 설정이 복잡하고, 테스트 코드를 작성해야 하므로 초보자에게는 다소 어렵습니다. 실시간 반영이 어렵습니다.
  • 사용 시기: 대규모 프로젝트에서 문서의 정확성과 유지보수성을 중시할 때 적합.

 

사용 현황

기업유형	선호하는 방식	이유
대기업/금융권	Spring REST Docs	코드 품질, 테스트 기반 문서화
스타트업/중소기업	Swagger	빠른 개발, 즉시 테스트
최근 트렌드	둘 다 사용	REST Docs(정적) + Swagger(테스트)