API 문서화 - swagger ( springboot )

개발을 진행함에 있어 작성한 코드를 기록하고 누구나 이해하기 쉽게 남기는 것은 너무나 중요한 사항이다.

이러한 것들을 직접 손으로 기록하여 메신저를 통해 다른 사람에게 전달하는 방식도 물론 있으나 이러한 과정 없이 자동으로 내가 만들어낸 API를 문서화 시켜주는 도구들이 여럿 존재한다. ( swagger, postman, spring rest docs 등등 .. )

그중 이번에는 스웨거 ( sawgger ) 에 대해 소개하고 사용하는 방법을 작성하려 한다.

스프링부트에서 스웨거를 사용함에 있어 선택할 수 있는 사항이 크게 2가지가 있는데 Springfox와 Springdoc이다.

사실 사용함에 있어 큰 차이점이 있는 것은 아니지만 Springfox는 2020년을 기준으로 업데이트를 중단했기 때문에 특별한 이유가 없다면 Springdoc를 사용하는 것을 추천한다.

 

Gradle

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

Maven

<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.6.0</version>
</dependency>

2024.07.14 기준으로 가장 최신 버전을 사용했으나, 필요에 따라 변경하여 사용하면 된다.

해당 페이지에서 버전을 확인하자!

https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-starter-webmvc-ui

해당 의존성을 build.gradle 등의 파일에 추가하고 오른쪽 상단에 보이는 버튼을 누른 후 코드를 실행 시키게 되면 http://localhost:8080/swagger-ui 주소에 접속할 수 있는 것을 확인할 수 있을 것이다! 

이미 작성해둔 코드가 있는 사람은 밑에 API 목록이 함께 보이겠지만, 프로젝트를 방금 막 생성한 사람들에게는 위와같은 화면이 보일 것이다

그렇기에 우리는 스웨거가 정상적으로 작동을 하는지 확인하기 위해 간단한 코드를 작성해볼 것이다.

위와 같은 경로에 Controller라는 파일을 생성하고 (파일명 자유롭게 해도 상관 없음), 아래 코드를 작성한 후 다시 코드를 실행 시켜보자.

( 아래 코드는 localhost:8080/api/test 라는 주소에 요청을 보냈을 때, test 라는 값을 반환 받는 코드이다. )

package com.study.study.test;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RequestMapping("/api")
@RestController
public class Controller {
    @GetMapping("/test")
    public String test(){
        return "test";
    }
}

그럼 아래와 같이 방금 작성한 코드가 문서화가 되어 표시되는 것을 확인할 수 있을 것이다.

추가된 api/test를 클릭하고 테스트해보면, “test”라는 반환 값을 받는 것을 확인할 수 있다.

 

처음 코드를 작성하는 사람에게는 위와 같이 스웨거의 기본 설정으로 사용하여도 큰 문제는 없을 것이라 생각하지만, 스웨거에서는 생각보다 많은 것들을 할 수 있기 때문에 상세한 내용은 다음 글에서 자세하게 다뤄보려한다.