[Springboot] 7. 스프링에서 REST API 명세를 문서화하는 방법 - Swagger

1. API 명세란?

API를 개발하면 명세를 관리해야 합니다. 명세란 해당 API가 어떤 로직을 수행하는지 설명하고 이 로직을 수행하기 위해 어떤값을 요청하며, 이에 따른 응답값은 무엇인지를 정리한 자료입니다.

 

2. Swaager 사용 이유

API는 개발 과정에서 계속 변경되므로 명세도 주기적으로 업데이트 해야합니다. 하지만 해당 작업은 번거롭고 오래걸립니다. 해당 문제를 해결하기 위해 등장한것이 Swagger 라는 오픈소스 프로젝트입니다.

 

3. Swagger 설정

3-1. pom.xml 의존성 추가

Swagger 의존성 추가

3-2. /config/SwaggerConfiguration.java 생성 후 설정

SwaggerConfiguration.java 클래스 추가

- RequestHandlerSelectors.basePackage() 메서드를 사용해  Swagger에서 스캔 할 패키지 범위를 설정

- 애플리케이션 기동 후 http://localhost:8080/swagger-ui.html 접속하여 Swagger 페이지를 확인 할 수 있음

Swagger 메인 페이지

3-3. 이전 API 코드 변경하여 명세 세부 내용 설정

3-3-1. @ApiOperation :대상 API의 설명을 작성하기 위한 어노테이션

3-3-2. @ApiParam : 매개변수에 대한 설명 및 설정을 위한 어노테이션입니다. 메서드의 매개변수뿐 아니라 DTO 객체를 매개변수를 사용 할 경우 DTO 클래스 내에 매개변수에도 정의 할 수 있습니다.

- 위의 설정 후 Swagger 페이지 확인

@ApiOperation , @ApiParam 를 활용

Excute 버튼을 눌러 API 테스트

테스트 결과