1. Swagger란?

• Swagger는 애플리케이션의 RESTful API 문서를 자동으로 구성하는 모듈이다.
• 또한 요청을 보내고 응답을 수신하여 작동 중인 엔드포인트를 즉시 테스트할 수 있다.

2. springdoc-openapi 의존성 추가

• springdoc-openapi 라이브러리는 swagger-annotations 과 swagger-ui 공식 라이브러리에 의존하여 OpenAPI로 화면을 구성하여 보여준다.

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'

3. API 문서 확인

• http://localhost:8080/swagger-ui/index.html
• 각 메서드에서 Try it out 버튼을 통해 직접 API를 호출하여 포스트맨과 같은 툴 처럼 테스트할 수 있다.

4. Swagger 애노테이션

• @Tag, @Operation, @ApiResponse, @Parameter 네 가지 애노테이션을 통해 API와 파라미터에 상세 정보를 추가할 수 있다.

/**
 * 제목 키워드 검색 일정 목록 조회 메서드
 * @param keyword 검색 키워드
 * @return 일정 목록
 */
@GetMapping("/schedules/contents")
@Operation(summary = "키워드 일정 목록 조회", description = "키워드 검색을 통한 일정 목록을 조회합니다.")
@ApiResponse(responseCode = "200", description = "성공")
@ApiResponse(responseCode = "400", description = "파라미터 오류")
public List<ScheduleResponseDto> getSchedulesByKeyword(
        @Parameter(required = true, description = "검색 키워드")
        String keyword) {
    return scheduleService.getSchedulesByKeyword(keyword);
}

5. Spring REST Docs VS Swagger

• Swagger는 UI를 통해 API 명세를 확인함과 동시에 테스트도 할 수 있는 장점이 있지만, 컨트롤러 코드애 Swagger 애노테이션을 추가해야 한다는 단점이 있다.
• 스프링 REST Docs는 테스트 코드 기반으로 문서를 생성하므로 애플리케이션 코드와 API 명세를 위한 코드가 분리된다. 하지만 정적인 문서만 생성하므로 테스트가 불가능하다.