프론트가 혼란에 빠지지 않는 서버와 API 문서 만들기

이전 노션 블로그의 Transaction 이란? (2023.08.11)로부터 마이그레이션된 글입니다.

 

 

저는 늘 Swagger의 자동화와 간단한 어노테이션을 통해 빠른 API 문서 배포만 해봤습니다. 빠르게 작업가능하다는 장점은 있었지만, 모든 요청을 Postman으로 테스트하는 과정에서 실수가 있을 수 밖에 없었고 Swagger의 자동 생성 문서가 친절한 편은 아니기에 읽는 사람마다 다르게 이해되는 경우가 있었습니다. 따라서 프론트에서 API를 연결하는 과정에서 실수가 자주 발생하거나, 오류가 발생하더라도 저에게 직접 물어보는 경우가 많았습니다. API 문서를 작성한 의의가 사라져버리는 일이 많았습니다… 😔

이번 리뷰메이트 프로젝트에서는 제한된 시간 내에 FE와 AI 모두가 사용할 서버를 만들어야 하므로, 신뢰성이 높고 명료한 API 문서를 만들기 위해 공부하고 고민한 과정을 정리해보았습니다.

 

 

---

API 문서화 도구 비교

Spring 기반 서버 프로젝트에서 API 문서화는 대게 Swagger와 Spring RestDocs를 사용하고, 두 개의 장점만 가져가기 위한 OpenAPI Specification(OAS)기반 Swagger가 있습니다. (OAS기반 Swagger는 epages라는 회사가 만든 OAS 추출 및 Swagger 적용 오픈소스를 통해 주로 사용되므로, 이하 epages라고 부르겠습니다)

Swagger		RestDocs		epages
장점	단점	장점	단점	장점	단점
깔끔하고 예쁜 문서	테스트 코드를 강제하지 않으므로, 높지 않은 신뢰도	테스트 코드 작성 강제로 인한 높은 신뢰도	우아하지 못한 문서	Swagger의 우아한 문서 (깔끔하고 예쁘며, API Test 기능)	도큐먼트가 없고, 트러블슈팅을 위한 참고자료도 적음
API Test 기능 지원	Swagger 어노테이션이 비즈니스 코드와 섞임	비즈니스 코드와 문서화 코드가 분리됨	API Test 기능 미지원	테스트 코드를 기반으로 작성되므로 높은 신뢰도	Swagger와의 RestDocs 차이로 인해 잘못 작성되는 문서

 

Swagger

Swagger는 굉장히 우아한 문서가 특징입니다. 문서가 예쁘며, 제공하는 정보량 또한 많습니다. 파라미터의 종류와 예시, response, 리턴 혹은 첨부되는 DTO의 스키마 등등이 제공되며, 사용자가 별도로 이를 명시하지 않으면 서버의 코드를 바탕으로 작성되는 특징 덕분에 단순 노동에 가까운 코드 작성 시간을 단축시켜줍니다.

설명만 들으면 별것 아닌 것 같은 장점같지만, RestDocs를 써보고 나면 그 장점을 절실히 느끼게 됩니다…

하지만 이 장점을 상쇄시킬 정도로 치명적인 단점이라면, API 문서에 내용들 추가 작성하기 위한 어노테이션들이 비즈니스 로직과 섞인다는 점입니다. DTO의 경우에는 양호한 편이지만, Controller는 완전히 혼란스러워집니다.

 

RestDocs

컨트롤러 테스트 코드를 기반으로 API 문서과 작동되기 때문에, 신뢰성 높은 요청만 문서에 기재되는 특징이 있습니다. 어찌보면 반자동화라고 볼 수도 있을 것 같습니다. RestDocs는 Asciidoctor 문서를 통해 API 문서를 생성하는데, 이 API 문서가 우아하지 못하다는 점이 큰 단점입니다. Swagger에 익숙한 저에겐 역체감이 심해서 그렇게 느끼는 것일지 모르겠지만, 예쁘지 못한 문서는 가독성마저 헤칩니다. 그리고 문서에서 제공되는 정보량도 Swagger 대비 적습니다. 특유의 문법으로 인한 단점은 epages도 마찬가지이므로, 후술하겠습니다.

 

epages, OpenAPI Specification(OAS) 기반 API 문서화

OpenAPI Specification(OAS)는 RESTful API 스펙 문서의 표준으로서 활용되고 있는 규악입니다. Swagger-UI는 OAS를 해석하여 API 스펙을 시각화해줍니다. 또한 Postman, Paw같은 API Client들도 OAS를 지원하고 있어 활용도가 다양합니다.

restdocs-api-spec 오픈소스

이 원리를 이용해서, epages는 제공하는 **RestDocs Wrapper 클래스로 테스트 코드를 작성하면 OAS를 추출해줍니다. 그러면 static routing을 통해 추출된 OAS를 기반으로 swagger 페이지를 호스팅**하게 됩니다. 즉, 문서 작성은 RestDocs, 문서 제공은 Swagger를 사용하므로 두 장점만 택하는 방식이므로 장점만 있을 것 같아보였지만, 제가 적용하면서 만난 문제들을 소개해 드리겠습니다.

 

epages 트러블슈팅

부족한 참고자료

epages는 2가지 방법으로 사용할 수 있습니다.

1. RestDocs의 문법과 유사하지만, epages 독자적인 ResourceSnippetParameters.builder() 패턴을 사용한 API 문서 작성
2. RestDocs와 똑같은 문법으로 작성된 코드에, epages가 제공하는 RestDocs Wrapper 클래스로 교체

1번 방식은 독자적인 방식이기 때문에 관련 자료를 참고하면서 사용해야 하지만, 참고자료가 부족합니다. 우선 OAS기반 API 문서화는 일반 개발 블로그에서는 잘 소개되지 않고 있고 카카오 페이나 컬리 등의 일부 테크 블로그에서만 소개되고 있습니다. 즉, 다양한 환경에서 적용을 시도한 기록이나 그 과정에서 발생한 트러블을 해결한 기록에 대한 자료가 거의 없습니다.(물론 영어로 검색해도 마찬가지..) 공식 도큐먼트 또한 존재하지 않고, 레퍼지토리의 README에 간단한 setup과 사용법에 대해서만 소개하고 있습니다.

클래스를 뜯어가면서 사용해가려고 했지만 디버깅에 너무 많은 시간이 소모되었기 때문에, RestDocs 자료를 참고할 수 있는 2번 방식으로 시도하였습니다.

@ModelAttribute, @RequestParts 대응

리뷰메이트의 리뷰 업로드와 상품 추가 요청은 DTO와 사진 MultipartFile을 한 번에 처리합니다. 두 파라미터는 Content-type 도 구분해서 보내야하는 만큼 문서화가 중요한 POST 요청입니다만, epages에서는 제대로 문서화되지가 않았습니다.

⚠️ 우선 epages의 OpenAPI를 2버전으로 낮춰야 합니다.

• OpenAPI 2.0 ⇒ RestDocs 2.0.X
• OpenAPI 3.0 ⇒ RestDocs 3.0.X

와 같이 대응되는데, RestDocs 3.0.X 부터는 @ModelAttribute 와 @RequestParts 파라미터를 대응하는 requestParts 지원이 삭제되었습니다. Form parameter와 QueryParameter를 구분하기 위한 변경사항이라고 적혀있지만, mockMvc의 mulipart() 요청으로 전달되는 multipartFile 파라미터는 어떻게 대응해야하는지에 대한 문서가 없고, 구글링해도 찾을 수 없었습니다.

OpenAPI 2.0 이 제대로 문서화되지 않는 점을 다루고 있지만, OpenAPI 3.0 은 컴파일 조차 안되므로, 버전을 낮춰야합니다.

@ModelAttribute 와 @RequestParts 파라미터를 대응하는 requestParts() 는 문서화되지가 않습니다.

// ReviewController
@PostMapping("/")
public ResponseEntity<Void> createReview(@Valid @ModelAttribute ReviewCreateRequest reviewCreateRequest) {
    Long reviewId = 1L;

    return ResponseEntity.created(URI.create("/api/v1/review/" + reviewId)).build();
}

// ReviewCreateRequest
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class ReviewCreateRequest {

    @NotNull
    private Integer rating;

    @NotBlank
    private String title;

    @NotBlank
    private String content;

    private List<MultipartFile> reviewImages;

    @NotNull
    private Long travelProductId;

    @NotNull
    private Long customerId;
}

@Test
void 리뷰를_생성한다() throws Exception {

    // when
    ResultActions response = mockMvc.perform(
                    multipart("/api/v1/review/")
                          .file("reviewImages", testImage1.getBytes())
                            .param("rating", "5")
                            .param("title", "리뷰 제목")
                            .param("content", "리뷰 내용")
                            .param("travelProductId", "1")
                            .param("customerId", "1")
                            .contentType(MediaType.MULTIPART_FORM_DATA)
            )
            .andExpect(status().isCreated())
            .andExpect(header().string(HttpHeaders.LOCATION, "/api/v1/review/1"));

    // then
    response.andDo(
            document("review-createReview",
                    requestHeaders(
                            HeaderDocumentation.headerWithName(HttpHeaders.CONTENT_TYPE).description(MediaType.MULTIPART_FORM_DATA_VALUE)
                    ), requestParts(
                            partWithName("reviewImages").description("리뷰 이미지 파일")
                    ), requestParameters(
                            RequestDocumentation.parameterWithName("rating").description("별점"),
                            RequestDocumentation.parameterWithName("title").description("리뷰 제목"),
                            RequestDocumentation.parameterWithName("content").description("리뷰 내용"),
                            RequestDocumentation.parameterWithName("travelProductId").description("여행 상품 ID"),
                            RequestDocumentation.parameterWithName("customerId").description("고객(업로더) ID")
                    ))
    );
}

List<MultipartFile> reviewImages &nbsp; 가 표현되지 않은 모습

 

@PostMapping("/request-part")
public ResponseEntity<Void> createReview(@Valid @RequestPart("reviewCreateRequest") ReviewCreateRequest reviewCreateRequest,
                                         @RequestPart("reviewImages") List<MultipartFile> reviewImages) {
    Long reviewId = 1L;

    return ResponseEntity.created(URI.create("/api/v1/review/" + reviewId)).build();
}

@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class ReviewCreateRequest {

    @NotNull
    private Integer rating;

    @NotBlank
    private String title;

    @NotBlank
    private String content;

    @NotNull
    private Long travelProductId;

    @NotNull
    private Long customerId;
}

@Test
void 리뷰를_생성한다_request_part() throws Exception {

    String content = objectMapper.writeValueAsString(new ReviewCreateRequest(5, "리뷰 제목", "리뷰 내용", 1L, 1L));
    MockMultipartFile json = new MockMultipartFile("reviewCreateRequest", "", "application/json", content.getBytes());

    // when
    ResultActions response = mockMvc.perform(
                    multipart("/api/v1/review/request-part")
                            .file("reviewImages", testImage1.getBytes())
                            .file(json)
                            .contentType("multipart/mixed")
                            .accept(MediaType.APPLICATION_JSON)

            )
            .andExpect(status().isCreated())
            .andExpect(header().string(HttpHeaders.LOCATION, "/api/v1/review/1"));

    // then
    response.andDo(
            document("review-createReview-request-part",
                    requestHeaders(
                            HeaderDocumentation.headerWithName(HttpHeaders.CONTENT_TYPE).description(MediaType.MULTIPART_FORM_DATA_VALUE)
                    ), requestParts(
                            partWithName("reviewImages").description("리뷰 이미지 파일"),
                            partWithName("reviewCreateRequest").description("리뷰 이미지 파일")
                    ))
    );
}

@RequestPart 파라미터에 해당하는 DTO와 Multipart list 모두 표현되지 않는 모습

즉, MultipartFile이나 RequestPart 파라미터들이 제대로 문서화되지 않는 모습이므로, 이 파라미터를 사용하지 않으면서 epages의 장점을 가져가고 싶다면 고려해볼만 한 것 같다.

 

Swagger와 RestDocs간의 타입 지정 형식의 불일치

바로 위에서 소개한 @ModelAttribute를 포함하여 PathVariable 등 reqeustParameters() 에 해당하는 파라미터들은 타입을 지정할 수 없고, 오직 json 형식 파라미터들만 requestFields() 타입을 지정할 수 있다. 입력 뿐만 아니라 반환에서도 json 형식의 데이터 객체만 타입을 명시할 수 있다.

단순히 타입을 표현할 수 없다는 것 또한 단점이지만, 문제는 Swagger에 표현될 때가 문제다. Swagger는 모든 입력 및 반환 데이터의 데이터가 명시되기 때문에 RestDocs에서 명시하지 못한 데이터들은 기본값인 string으로 지정된다. 이는 API 사용자들에게 오해를 불러일으킬 수 있다고 생각한다.

 

 

---

나의 선택

따라서 epages는 아직 프로젝트에 도입하기 이르다고 판단하였기 때문에, Swagger를 도입하되 그 단점을 보완하는 방향을 선택하였다.

강제되지 않는 테스트 코드인한 부족한 신뢰도

mockMvc와 andExpect() 를 이용하여, 컨트롤러마다 테스트 코드를 적용했다.

 

어노테이션과 비즈니스 로직이 섞임으로 인한 가독성 문제

공백을 최대한 활용하고 Controller를 세분화하여, 어노테이션을 주석정도로 느낄 수 있는 선으로 가독성을 유지하기 위해 노력했다. 아래 사진은 ReviewController 이고, 리뷰의 직접적인 CRUD의 요청만 들어있고, 리뷰 분석결과에 해당하는 요청들은 ReviewTagController 로 분리하였다.

자세하고 정보량이 많은 문서

Swagger가 코드를 감지하여 자동으로 문서를 작성해주지만, 어노테이션을 통해 추가적인 정보와 필요할만한 정보를 최대한 자세히 적고, Swagger의 API Test 기능을 적극 활용하도록 세팅할 예정이다. 다음은 그 과정과 과정 중에 있던 트러블슈팅을 분석해본 포스팅이다.

Swagger에서 MultipartFile과 DTO 한 번에 받는 @RequestPart 요청을 실행할 수 있도록 만들기

 

실제 코드와 문서가 달라지는 문제

이 문제는 어노테이션 작성하는 도중 실수하거나 컨트롤러를 리펙토링하고 나서 반영하지 않아서 발생하는데, Github Copilot를 이용하여 많이 보완할 수 있었다.

리팩토링하고 나서, 변경된 어노테이션을 지웠다가 코파일럿을 통해 다시 작성하면 95%정도는 정상적으로 작성되었다. 5%정도의 오차 중에 3%는 나의 실수 때문에 발생한 것이었는데, 코파일럿은 내가 작성한 코드를 바탕으로 자동완성시켜주기 때문에 리턴 값이라던가 매개변수 등에 잘못 작성한 코드가 있을 경우 자동완성되는 코드 또한 잘못된다.

만약 내가 작성한 API 문서와 유사한 형태로 자동완성시켜 주고 싶은 경우, IDE에 참고할 다른 코드를 띄어놓는다면 코파일럿이 이미 작성된 유사한 코드를 참고하여 자동완성시켜 준다. 아래는 참고할 코드를 안띄운 자동완성과 띄운 자동완성을 비교한 것이다. 원래는 @APIResponse 의 @Header 어노테이션의 description 부분에 URL 이 추가 되지 않았지만, 참고할 코드를 띄우고 나서는 URL까지 추가되는 모습을 볼 수 있다.

 

 

---

마치며

OAS기반 Swagger라는 새로운 기술을 도입하여 기존의 문제를 해결하기 위해 긴 시간 노력하였지만, 단점의 발견으로 다시 원래대로 돌아오지만 단점을 최대한 상쇄하는 방향으로 마무리 되었다. 이후에 다양한 Swagger 어노테이션을 통해 API 문서작성하는 과정에서 진행한 다양한 트러블슈팅은 아래의 게시글에 이어가 볼 예정이다.

Swagger에서 MultipartFile과 DTO 한 번에 받는 @RequestPart 요청을 실행할 수 있도록 만들기

OAS 빌드 및 Swagger 반영 자동화 그레이들

혹시 나의 단점 분석이 잘못되었거나 단점을 감안하고도 epages를 쓰고 싶다면, OAS 추출 및 반영 자동화를 위해 작성한 나의 그레이들 코드를 참고하길 바란다. epageSwagger 테스크를 실행하면, 변경된 컨트롤러와 테스트를 반영하여 빌드하고, Swagger에 반영하는 자동화이다. 기존의 빌드파일을 지우고 빌드하지 않으면, 삭제된 컨트롤러가 반영되지 않는 문제를 발견해서 만들었다.

openapi3 {
    servers = [{ url = "https://localhost:8080/" }]
    title = "Review Mate API"
    description = "Review Mate WAS API"
    version = "0.1.0"
    format = "yaml"
}

tasks.named('test') {
    useJUnitPlatform()
}

tasks.register('clearSwagger') {
    mustRunAfter('test')

    doLast {
        delete("build/")
        println "::: 1. Clear 'build/'"

        delete("src/main/resources/static/swagger-ui/openapi3.yaml") // 기존 OAS 파일 삭제
        println "::: 2. Delete 'rc/main/resources/static/swagger-ui/openapi3.yaml'"
    }
}

tasks.register('runOpenApi3') {
    mustRunAfter('clearSwagger')

    doLast {
        exec {
            commandLine './gradlew', 'openapi3'
        }
        println "::: 3. Run openapi3'"
    }
}

tasks.register('copyOasToSwagger') {
    mustRunAfter('runOpenApi3')

    doLast {
        copy {
            from "$buildDir/api-spec/openapi3.yaml" // 복제할 OAS 파일 지정
            into "src/main/resources/static/swagger-ui/." // 타켓 디렉토리에 파일 복제

        }
        println "::: 4. Copy OAS file to swagger-ui"
    }
}

tasks.register('epagesSwagger') {
    doFirst {
        println ":: 0. Run ePages Swagger'"
    }

    dependsOn 'test'
    dependsOn 'clearSwagger'
    dependsOn 'runOpenApi3'
    dependsOn 'copyOasToSwagger'
}

tasks.named('build') {
    dependsOn 'copyOasToSwagger'
}

 

참고자료

https://tech.kakaopay.com/post/openapi-documentation/#13-swagger-file-수정

https://helloworld.kurly.com/blog/spring-rest-docs-guide/

https://luvstudy.tistory.com/186

https://yongc.tistory.com/18

https://github.com/spring-projects/spring-restdocs/wiki/Spring-REST-Docs-3.0-Release-Notes

https://ykh6242.tistory.com/entry/Spring-Web-MVC-Multipart-요청-다루기

https://velog.io/@tmdgh0221/Spring-Rest-Docs-적용해보기

https://techblog.woowahan.com/2597/

https://discuss.gradle.org/t/what-is-dolast-for/27731

https://kotlinworld.com/322