스프링은 다 알고 있다! - 평범한 개발자의 Swagger 어노테이션 지옥 탈출기

4개월·

894

안녕하세요, 평범한 서버 개발자입니다.

발단

사이드 프로젝트 하다가 Swagger 문서화를 하게 됐는데요.

@Operation(summary = "유저 조회", description = "ID로 유저를 조회합니다")
@ApiResponses({
    @ApiResponse(responseCode = "200", 
        description = "성공",
        content = @Content(schema = @Schema(implementation = UserDto.class))),
    @ApiResponse(responseCode = "404", description = "유저 없음")
})
@Parameter(name = "id", description = "유저 ID", required = true)
@GetMapping("/users/{id}")
public UserDto getUser(@PathVariable Long id) {
    return userService.findById(id);
}

3줄짜리 메서드에 어노테이션이 10줄...

이거 엔드포인트마다 달다가 문득 이런 생각이 들었습니다.

"잠깐, 이거 스프링이 이미 다 알고 있는 정보 아니야?"

전개

생각해보면:

경로? @GetMapping에 있음. 스프링이 앎.
HTTP 메서드? @GetMapping이니까 GET. 스프링이 앎.
파라미터? @PathVariable Long id. 스프링이 앎.
응답 타입? UserDto 반환. 스프링이 앎.

스프링은 이미 다 알고 있습니다.

RequestMappingHandlerMapping이라는 놈이 런타임에 모든 매핑 정보를 들고 있거든요. 근데 우리는 Swagger한테 이걸 또 알려주고 있었던 겁니다. 수동으로. 하나하나.

위기 (빡침)

그래서 빡쳐서 만들었습니다.

SASA (Spring API Spec Analyzer)

스프링한테 "야 너 API 정보 다 알고 있잖아, 그거 좀 줘" 하고 물어보는 라이브러리입니다.

절정 (사용법)

@SpringBootApplication
public class MyApplication {
    public static void main(String[] args) {
        var context = SpringApplication.run(MyApplication.class, args);
        var mapping = context.getBean(RequestMappingHandlerMapping.class);
        
        // 스프링아 API 스펙 줘
        SasaApplication.generateApiSpec(mapping, context);
    }
}

실행하면: