Springdoc OpenAPI(1) - API 명세서 도입

Dong·2025년 3월 8일

Spring

목록 보기

1/4

도입 이유

Spring Boot를 사용한 백엔드 서버에서 만들어진 API를 노션을 통해 프론트엔드 개발자와 기획자에게 전달하고 있었다. 하지만 노션으로 작성한 기존 API 명세서들을 좀 더 UI/UX 친화적인 방법으로 제공할 방법이 없을까라는 고민에서 API 명세서 툴과 라이브러리를 찾아봤다.

Option 1. Notion

Notion site

기존에 사용하고 있었던 툴이었으므로 페이지만 새로 추가해서 API 명세서를 작성할 수 있었다.
비개발자인 기획자분들도 쉽게 사용할 수 있어서 협업에 용이했지만, 작성된 예제들을 결국엔 postman과 같은 툴을 사용해서 API 테스트를 해야 한다는 불편함이 많았다. 또한, 협업용으로 사용하는 노션은 유료기도 했다.

(Notion 예시)

Option 2. Postman

Postman site

만들어진 API를 테스트하기 위해서 사용했었던 Postman에서도 API 명세서를 지원한다고 해서 테스트해 봤다.
사용 방법은 Postman에서 제공해 주는 reference를 따라 하면 기존 Postman에서 작성한 테스트를 통해 API 명세서를 쉽게 만들 수 있었다. 하지만 협업을 위해서 여러 개발자가 같은 Collection에서 작업하려고 초대하면 요금이 부과됐었다.
(Postman 예시)

Option 3. Swagger - Springdoc OpenAPI

OpenAPI 공식 문서
springdoc openapi

OpenAPI는 현재 REST API 명세의 공식 표준으로 이전 Swagger 2.0에서 발전해서 만들어졌다고 한다. Swagger는 OpenAPI를 구현하기 위한 툴 중에 하나라고 보면 된다고 한다.
현재 사용 중인 SpringBoot 3.x 버전에서 사용할 수 있는 OpenAPI 문서를 만들어주는 라이브러리인 Springdoc OpenAPI를 테스트해 봤다.
간단히 테스트해 본 결과 코드 내에서 어노테이션을 통해 API의 설명 등을 적을 수 있었고, 예시 또한 적을 수 있어 화면을 통해 쉬운 테스트가 가능했다. 그리고 오픈소스라서 무료로 이용할 수 있었다.
자세한 내용은 아래 적힌 내용들과 후 포스트에서 적을 예정이다.

정리 및 선택

툴/라이브러리	장점	단점
Notion	비개발자 접근성 우수	프로젝트에서 사용할때는 유료
Postman	API 테스트 기반 문서화 가능	프로젝트에서 사용할때는 유료
OpenAPI(Swagger)	무료. 코드 기반 자동 문서화 가능	화면 커스터마이징이 어려워보임

우리는 Spring Boot를 통해 깔끔한 기본적인 UI/UX를 사용 가능하고 비용도 아낄 수 있는 Springdoc-openapi 라이브러리를 사용하게됐다.

설정

Spring Boot 3.4.3

gradle

implementation 'org.springframework.boot:spring-boot-starter-web' // web
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.5' // openapi(swagger)

예시

다음과 같이 Controller 메서드 위에 어노테이션을 통해 HttpMethod와 URI, API에 대한 설명 등을 작성할 수 있다.

@RestController
@RequestMapping("/customer")
@AllArgsConstructor
public class CustomerController {

    private final CustomerService customerService;

    @PostMapping("")
    @Operation(description = "고객 등록", tags = "고객")
    public ResponseEntity<ResponseMessage> saveCustomer(@RequestBody CustomerDto customerDto){

        long id = customerService.saveOneCustomer(customerDto);

        return ResponseEntity.ok(ResponseMessage.success(id));
    }
}