스웨거 사용해보기 1: 기본 설정

스웨거

팀 프로젝트를 하면서 프론트엔드와 백엔드 간에 API 명세서가 필요해졌다.

전엔 스웨거를 안써서 노션에 수동으로 API 명세서를 작성하고 수정했었다.

그래서 최신화가 안되는것도 많았는데 이번엔 API 문서 자동화 툴인 스웨거를 이용해보기로 했다.

---

사용 기술

• Spring Boot 3.2.4 / gradle-kotlin
• Java 17
• Swagger

---

1. 의존성 추가

스웨거를 사용하기 위해 의존성을 추가해준다.

스웨거도 버전이 여러가지인듯 하므로 적당히 취향껏 쓰면 될것 같다.

본인이 사용한 스웨거 라이브러리는 이쪽 링크에서 확인할 수 있다. 

// build.gradle.kts
// swagger
implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.4")

---

2.  SwaggerConfig 설정

스웨거를 사용하기 위해서는 Config 설정이 필요하다.

아래와 같은 기본 설정을 해주면 사용할 수 있다.

SwaggerConfig

@Configuration
@RequiredArgsConstructor
public class SwaggerConfig {

    @Bean
    public OpenAPI serverApiConfig() {
        return new OpenAPI()
            .info(new Info().title("PAWLAND API")
                .description("PAWLAND API SWAGGER UI입니다."));
    }
}

---

3.  컨트롤러에 스웨거 UI 표기용 설정

UserController

스웨거는 기본적으로 아래처럼 애노테이션을 붙이는 식으로 UI에 표시한다.

참고로 스웨거를 사용하면 기본적인 요청, 응답 DTO는 알아서 맵핑해준다.

@ModelAttribute 로 쿼리스트링을 여러개 받는 경우는 따로 애노테이션을 붙여야하지만 다음에 다뤄보겠다.

@RestController
@RequestMapping("/api/user")
@RequiredArgsConstructor
@Tag(name = "UserController", description = "유저 정보 관련 컨트롤러 입니다.")
public class UserController {

    private final UserService userService;

    @PreAuthorize("hasRole('ROLE_USER')")
    @Operation(summary = "내 정보 조회", description = "JWT로 내 정보를 조회합니다.")
    @ApiResponse(responseCode = "200", description = "내 정보 조회 성공")
    @ApiResponse(responseCode = "500", description = "삭제된 회원 또는 잘못된 JWT")
    @GetMapping(value = "/my-info", produces = MediaType.APPLICATION_JSON_VALUE)
    public ResponseEntity<UserInfoResponse> getUserInfo(@AuthenticationPrincipal UserPrincipal userPrincipal) {
        UserInfoResponse userInfo = userService.getUserInfo(userPrincipal.getUsername());
        return ResponseEntity
                .status(OK)
                .body(userInfo);
    }
}

 

ㄴ@Tag

아래 사진에서 보듯 컨트롤러의 최상단의 그룹 이름과 설명을 표시할 수 있다.

ㄴ@Operation

각각의 컨트롤러에 대한 이름과 설명을 표시할 수 있다.

ㄴ@ApiResponse

각각의 응답 코드에 따른 설명을 표시할 수 있다.

---

4. 결과 확인

포트번호가 8080 기준으로 http://localhost:8080/swagger-ui/index.html 로 들어가면 스웨거를 확인할 수 있다.