[Independe] 협업을 위한 첫걸음 Swagger

난 자취생 커뮤니티 Independe가 첫 프로젝트였는데 팀원 역시 프로젝트 경험이 없었다. 팀원은 서버에 대한 개념조차 거의 없어 처음엔 통신을 어떻게 해야되는지도 잘 몰랐다. 그렇게 서로 학습을 하고 Vue.js와 Spring이 통신하기 위해선 REST API를 url을 통해 데이터를 주고 받는걸 알게됐다. 하지만 둘다 프로젝트는 처음이었기에 어떤 URL에 어떤 데이터가 맵핑되어있는지 서로에게 알려주기 너무 힘들었다.

 

부끄럽지만 처음엔 가장 단순한 방법인 카카오톡을 사용했다. 같은 교내 학술동아리라 다행히 옆 자리였기에 먼저 카톡으로 Url과 함께 데이터를 어떻게 전송해야되는지 보내주고 팀원은 이를 받은 뒤 개발하며 모르겠거나 오류가 발생하는 것은 옆에서 하나하나 물어보며 개발을 했다. 사실 처음엔 크게 불편함을 못 느꼈지만 API가 많아지고  데이터가 자주 변경돼 계속 카톡으로 보내주니 많은 혼선이 있었다. 그러다 우연히 현재도 많은 개발자들이 사용하고 있는 Notion을 발견했다. 물론 Notion을 API 문서로 사용하진 않지만 우리에겐 더할나위 없었다. 페이지를 만들어 Url을 적어놓고 아래에는 데이터 형식을 작성한 뒤 이를 계속 변경해서 사용했다.

그때 사용했던 노션중 일부인데 지금 다시보니 정말 부끄럽다. 그러나 카톡을 사용하던 우리에게 노션이 처음엔 정말 편했다. 하지만 이 역시 한계는 명확했다. 우선 직관성이 다소 떨어졌으며 Spring에서 데이터 형식을 변경한 후 내가 Notion에 반영하지 않으면 팀원은 알 수 없는 오류만 맞이할 뿐이었다. 그래도 카톡보단 낫지 라는 생각으로 개발을 해왔다. 그러던 중 난 구글링을 통해 다른 사람들의 개발 방식을 보던 중 드디어 Swagger를 발견했다.

 

Swagger란 개발한 REST API를 편리하게 문서화해주는 라이브러리이다. 처음엔 REST API를 '문서화'해준다 하여 PDF같은 형식으로 변환시켜 주는건가? 회사에서 많이 사용하나보다 라고 생각하여 그저 보고 넘겼었다. 하지만 다수의 개발자들이 Swagger를 사용하니 점점 더 호기심이 생겼고 난 Swagger에 대해 더 찾아보았다. 구글링을 해보니 REST API 문서화는 내가 생각한 것과 조금 달랐으며 단순히 PDF 방식으로 문서 파일을 주는것이 아닌 URL을 통해 현재 서버에 개발된 REST API를 모두 확인할 수 있었고 변경사항 역시 곧바로 적용됐다. 카톡과 Notion을 사용하던 나에겐 신세계였다. 곧바로 난 프로젝트에 적용할 방법을 찾아보았다.

 

적용방법은 생각보다 매우 단순했다.

// Swagger 추가
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'

build.gralde에 dependency를 추가하고

@OpenAPIDefinition(
        info = @Info(title = "IndependeApi",
                description = "Independe Api 문서")
)
@RequiredArgsConstructor
@Configuration
public class SwaggerConfig {

    @Bean
    public GroupedOpenApi openApi() {
        return GroupedOpenApi.builder()
                .group("independe")
                .packagesToScan("community.independe.api")
                .build();
    }

}

설정 클래스를 만들어 몇가지 설정만 하면 끝이었다.

이는 현재 나의 Spring 서버의 REST API를 Swagger로 나타낸 화면 중 일부이다. URL 뿐만 아니라 자동으로 데이터 전송방식에 대해서도 친절히 알려주었다. 

// 자취 게시글 생성
@Operation(summary = "자취 게시글 생성")
@PostMapping(value = "/api/posts/independent/new", consumes = {MediaType.MULTIPART_FORM_DATA_VALUE})
public ResponseEntity<Long> createIndependentPost(@Parameter(description = "제목") @RequestParam String title,
                                                  @Parameter(description = "내용") @RequestParam String content,
                                                  @Parameter(description = "자취 타입") @RequestParam IndependentPostType independentPostType,
                                                  @Parameter(description = "이미지") @RequestParam(required = false) List<MultipartFile> files,
                                                  @AuthenticationPrincipal MemberContext memberContext) throws IOException {
	// == 생략 == //
    
    
}

마지막으로 난 @Operation 애노테이션을 이용해 REST API에 대한 간단한 설명을 추가했다.

 

이후 팀원에게 Swagger에 대한 간단한 소개와 함께 Swagger url을 알려주었다. 팀원은 잠시 Swagger를 확인하고 코드를 몇번 만져보더니 정말 만족한 표정과 말투로 이걸 왜 이제야 적용하냐며 나에게 웃음섞인 핀잔을 주었다. 이후 우리는 노션과 카톡을 더 이상 사용할 필요 없었고 REST API 공유 방식에 대한 고민 또한 사라졌다. 나의 간단한 설정으로 인해 더욱 생산성 있게 개발을 하는 팀원을 보니 나 역시 매우 기뻤다. Swagger를 적용하며 난 협업에 대한 중요성을 조금 더 깨닫게 되었다.