Swagger - API 문서 자동화 사용기

🐈‍⬛ swagger

Swagger 는 REST API를 설계, 빌드, 문서화 및 사용하는 데 도움이되는 OpenAPI 사양을 중심으로 구축 된 오픈 소스 도구 세트이다. 애플리케이션의 API 문서를 자동으로 구성하는 특수 도구, 애플리케이션의 모든 엔드포인트를 살펴볼 수 있을 뿐만 아니라 요청을 보내고 응답을 수신하여 작동 중인 엔드포인트를 즉시 테스트할 수 있다.

 

🐈‍⬛ swagger 사용이유

🐾 사용이유는 곧 장점

• 테스트 할 수 있는 UI를 제공한다.
• 프로덕션 코드인 Controller가 곧 문서가 된다는 점에서 README.md 파일과 같이 별도로 관리할 문서가 없다.

🐈‍⬛ swagger 사용 배경

장바구니 협업 미션을 본격적으로 시작하기 위해 프론트엔드의 솔로스타, 네이브와 함께 API 설계를 진행했다. 

"클라이언트에서 어떤 요청이 들어오면 서버에선 이런 응답을 내려주면 좋겠다"

라는 대화가 여러번 오가며 아래와 같이 API를 완성했다.

 

API_최종

회의하는 자리에서 바로바로 이렇게 만들어주셔서 이것만 보고 구현을 해도 충분할 것이라 생각했다.

 

회의 끝나고 3시간쯤 지났나, 

띠링~

슬랙으로 솔로스타에게 DM이 왔다.

 

"REST API 명세를 한번 정리해보았어요! 초안으로 쓱 보시면 좋을 것 같습니다"

 

API_최최종

이런식으로 정말 예쁜 API 명세를 만들어주었고 우리는 구현의 처음부터 끝까지 이 API를 보면서 완성할 수 있었다.

 

그런데 구현을 하다보니 회의할 때 발견하지 못했던 변수나 추가사항들이 떠올랐고 이를 수정하려면 프로덕션 코드뿐만 아니라 README.md로 작성한 문서도 별도로 수정해야 했다. 

 

주드의 제안으로 swagger라는 문서 자동화 도구를 적용해봤는데 따로 관리할 문서도 필요 없고 프로덕션 코드만 변경하면 자동으로 업데이트 된다는 점에서 너무 좋다고 생각했다.

 

API_찐막 최최종

 

이쯤에서 사용 배경 얘기는 그만하고 swagger의 사용 방법에 대해 알아보자.

 

🐈‍⬛ swagger 사용 방법

Swagger를 Spring에서 쉽게 사용할 수 있도록 도와주는 Springfox와 Springdoc라는 라이브러리가 2개 존재하는데 이번 미션에선 Springdoc를 적용해보았다. Springfox를 적용한 다른 분들의 블로그를 보면 Configuration 정보도 변경해주는데 이번에 적용한 라이브러리 사용방법은 그리 복잡하지 않다.

🐾 의존성 추가

Swagger를 생성하고 작업하는데 있어서 필요한 의존성을 추가한다.

 

implementation 'org.springdoc:springdoc-openapi-ui:1.7.0'

 

🐾 Controller 설정

사실 설정이라고 할 것이 없지만

이렇게 api 상세 정보 설정을 위해  @Operation 어노테이션을 붙여준다.

summary 속성으로 API에 대한 간략한 설명, description 속성으로 API에 대한 상세 설명을 추가할 수 있으며, responses, parameters 속성 등을 추가로 적용할 수 있다.

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

import cart.domain.Member;
import cart.dto.response.ProfileResponse;
import io.swagger.v3.oas.annotations.Operation;

@RestController
public class ProfileApiController {

    @Operation(summary = "사용자 정보 조회")
    @GetMapping("/profile")
    public ResponseEntity<ProfileResponse> findProfile(@Auth Member member) {
        final int points = member.getPoints();
        return ResponseEntity.ok(new ProfileResponse(points));
    }
}

그러면 다음과 같이 summary 속성에 적어준 API 설명이 명시된다.

끝. 감사합니다.