서론

협업에서 REST API 문서는 빠질 수 없는 핵심 요소입니다.
잘 작성된 API 문서는 협업의 가치를 높이고 성공적인 프로젝트로 이끌어냅니다

REST API를 문서화하는 방법은 여러가지가 있습니다..
직접 작성할 수도 있고, 적합한 도구를 사용할 수도 있습니다.

효율을 생각하는 백엔드 개발자라면 분명 잘 갖추어진 도구를 사용할 것입니다.
문서화도 중요하지만 결국 개발이 핵심적인 업무이기 때문입니다.

따라서 해당 프로젝트도 도구를 사용해서 문서화 했습니다.

문서화 도구 선택과정

주로 선택하는 대표적인 API 문서화 도구는 다음 두 가지 입니다

• Swagger
• Spring REST Docs

Swagger vs Spring REST Docs

Swagger는 API를 문서화하고 테스트할 수 있는 오픈소스 프레임워크입니다.
애노테이션으로 간단하게 API 문서를 생성할 수 있으며, 자체 UI를 제공해서
쉽게 테스트할 수 있습니다.

Spring REST Docs는 테스트 기반으로 문서를 작성합니다.
테스트가 성공했을 때만 문서화하기 때문에 문서의 정확성을 보장합니다

Swagger를 선택한 이유

해당 프로젝트는 Swagger를 선택했습니다. 이유는 다음과 같습니다

• 개발 기간이 짧기 때문에, 빠른 문서화가 필요했다
• 테스트 코드를 작성할 시간이 부족해 Spring REST Docs를 사용하기 어려웠다

따라서 빠르고 간편하게 API문서를 생성할 수 있는 Swagger를 선택했습니다

Spring boot에서 Swagger를 사용해보자!

Swagger 초기 설정

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

springdoc-openapi라이브러리는 Swagger를 지원합니다.
따라서 해당 의존성을 추가하면 서버의 API를 자동으로 문서화할 수 있습니다

[OpenAPI와 Swagger의 차이는 무엇일까? ]
둘의 관계는 인터페이스와 구현체의 관계를 생각하면 됩니다
OpenAPI는 API를 설계하고 문서화하기 위한 표준 형식과 구조가 정의되어 있으며,
Swagger는 OpenAPI를 구현하고 사용하는 도구입니다

Swagger 설정 추가

@OpenAPIDefinition(  
        servers = {@Server(url = "${swagger.prod-url}", description = "운영 서버"),  
                   @Server(url = "${swagger.dev-url}", description = "개발 서버")  
        })  
@Configuration  
public class SwaggerConfig {  
  
    @Bean  
    public OpenAPI openAPI(){  
        return new OpenAPI().addSecurityItem(new SecurityRequirement()  
                        .addList("JWT AccessToken")  
                        .addList("JWT RefreshToken"))  
                .components(new Components().addSecuritySchemes("JWT AccessToken", createAccessTokenScheme())  
                        .addSecuritySchemes("JWT RefreshToken", createRefreshTokenScheme()))  
                .info(new Info().title("SheetPlus Application Server API")  
                        .description("SheetPlus Application Server API를 명세한 문서입니다.")  
                        .version("1.0 ver"));  
    }  
  
  
    private SecurityScheme createAccessTokenScheme() {  
        return new SecurityScheme()  
                .type(SecurityScheme.Type.HTTP)  
                .bearerFormat("JWT")  
                .scheme("bearer")  
                .description("JWT Access Token");  
    }  
  
    private SecurityScheme createRefreshTokenScheme() {  
        return new SecurityScheme()  
                .type(SecurityScheme.Type.APIKEY)  
                .in(SecurityScheme.In.HEADER)  
                .name("refreshToken")  
                .description("JWT Refresh Token");  
    }  
}

의존성 추가 이후, 설정 클래스를 만들어서 OpenAPI 빈을 등록합니다.
해당 빈에서 필요한 설정을 추가할 수 있습니다.

이제 OpenAPI 기반 Swagger-UI로 문서화된 API를 확인할 수 있습니다

JWT Token설정

프로젝트에서 JWT 토큰이 필요하기 때문에 해당 설정을 추가했습니다

우측 상단에서 버튼을 클릭해서 위 설정을 사용할 수 있습니다.

해당 버튼으로 Access Token과 Refresh Token을 등록하면,
URI마다 토큰 설정할 필요 없이 사용할 수 있습니다!

Server 선택창

또한 로컬서버와 운영서버를 직접 선택해서 어느 환경에서도
테스트할 수 있도록 Server 선택창을 추가했습니다.

자동화된 API 문서

이제 서버를 실행하고 swagger-ui/index.html경로로 접속하면
위와같이 컨트롤러 URI와 DTO 기반으로 API 문서를 자동 생성합니다

정리

이제 자동화된 API를 기반으로 백엔드 개발자도 편리하게 테스트하고 개발할 수 있으며,
프론트엔드 개발자와의 협업에서도 유용하게 사용할 수 있습니다!

이제 API문서가 완성되었으니 문서화 작업은 끝났습니다!

... 라고 끝마치기엔 너무 부실한 API문서입니다

Swagger API 문서를 더 세부적으로 작성하자!

자동으로 생성된 API 문서는 세부적인 내용이 부실합니다.
협업하는 개발자가 페이징 개념이나 offset과 limit의 의미를 명확히 알지 못한다면,
해당 문서만으로는 API 사용 방법을 완전히 이해하기 어려울 수 있습니다.

또한 MediaType 설명이나 응답코드에 대한 내용도 명확하게 작성되지 않았습니다.

이 문서가 협업 개발자에게 전달된다면, 커뮤니케이션 비용이 발생할 것입니다.
따라서 협업하는 개발자들가 이해하기 쉽도록, API문서를 더 구체적으로 작성해야합니다!

Swagger API문서를 세부적으로 작성하려면?

Swagger에서 제공하는 애노테이션을 사용하면 쉽게 작성할 수 있습니다!

@Tag

보통 Controller단위로 그룹을 짓는데 활용합니다
그룹 이름과 상세 설명을 포함할 수 있습니다.

@Operation

Controller의 URI에 활용합니다.
설명, RequestBody, Security 설정 등 다양한 정보를 작성할 수 있습니다.

@ApiResponse

응답코드를 기준으로 구분하며, 응답에 대한 상세 정보를 작성할 수 있습니다.
mediaType, 헤더 정보, ResponseBody정보 설정 등을 추가했습니다.

@Schema

DTO에서 활용할 수 있습니다.
DTO 클래스에 대한 설명이나 필드에 대한 정보를 포함할 수 있습니다

날짜타입 포맷설정 방법

LocalDateTime타입 필드의 초기 모습은 위와 같습니다

프로젝트에서 설정한 포맷은 'yyyy-MM-dd HH:mm:ss'로
'2025-01-05 13:11:45'와 같아야 하는데, 전혀 적용되지 않았습니다

@Schema(description = "Event 종료시간",  
        example = "2025-01-04 12:09:01", type = "string", pattern = "yyyy-MM-dd HH:mm:ss")

해결방법은 type을 string으로 지정하는 것입니다.

LocalDateTime으로 지정하거나 String으로 지정할 경우 적용되지 않으니
꼭 string으로 지정해야합니다!

string타입으로 @Schema를 설정하고 swagger를 다시 확인하면
잘 적용된 것을 확인할 수 있습니다!

응답 헤더 설정

GET 요청의 경우 Etag와 Cache-Control을 포함합니다.
특히 Etag의 경우, 네트워크 비용을 줄이기 위해 꼭 활용하는 방법이므로,
FE에서 활용하기 쉽도록 해당 정보를 명세해야합니다

headers = {@Header(name = "etag",  
        description = "\"etagexample\"과 같은 형태로 제공됩니다. If-None-Match속성에 Etag를 추가해서 요청하세요"),  
        @Header(name = "Cache-Control",  
                description = "클라이언트 캐시 사용, 캐싱 최대유효시간 1시간, 유효시간 지난 후에는 반드시 서버로 재요청하세요")}),

따라서 위와같이 @ApiResponse 설정 안에 header 설정을 추가했습니다

해당 정보가 포함된 것을 확인할 수 있습니다!

Response Body가 없는 경우, mediaType 설정 방법

Swagger는 @Content내용을 명시하지 않을 경우, 메소드 반환타입을 자동으로 적용합니다.

public ResponseEntity<List<ContestInfoResponseDto>> readContestInfo(  
        @Parameter(description = "조회할 페이지 번호", example = "1")  
        Integer offset,  
        @Parameter(description = "페이지당 조회할 데이터 개수", example = "1")  
        Integer limit  
){...}

위와같은 반환타입을 갖는 경우, @Content 설정을 하지 않아도

위와같이 Swagger가 메소드의 반환타입으로 자동 지정합니다.

해당 기능의 문제점은 응답 Body를 갖지 않는 경우에도 자동으로 적용된다는 점입니다.
대표적으로 304 응답처럼 Header만 보내는 경우입니다

해결방법은 Media type을 위와같이 None으로 지정하면 됩니다

@ApiResponse(responseCode = "304", description = "캐시 데이터의 변경사항이 없습니다. 로컬 캐시 데이터를 사용하세요",  
        content = @Content (mediaType = "None")),

적용 코드는 위와 같습니다!

Yaml로 추가 설정하기

application.yml로 추가적인 Swagger 설정이 가능합니다

springdoc:  
  swagger-ui:  
    groups-order: desc  
    tags-sorter: alpha  
    operations-sorter: method  
    disable-swagger-default-url: true  
    display-request-duration: true  
  default-consumes-media-type: application/json  
  default-produces-media-type: application/json

swagger-ui 경로 변경이나 정렬 방법, 기본 타입을 설정할 수 있습니다
또한 기본 Swagger-ui 설정의 경우 요청-응답시간이나 요청 경로에 대한 정보를 확인할 수 없는데

    disable-swagger-default-url: true  
    display-request-duration: true  

위 두 설정을 true로 바꾸면, 모두 확인 가능합니다

위와같이 요청경로와 요청-응답시간을 확인할 수 있습니다!

문서화 코드와 프로덕션 코드를 분리하자!

이제 처음보다는 더 상세한 정보가 포함된 API문서가 완성되었습니다
협업할 때, 해당 API문서를 효율적으로 활용가능합니다!

하지만 Swagger 코드를 작성할 경우 BE입장에서 한가지 문제가 발생합니다

@PostMapping("/contests/v1")  
@Operation(summary = "Contest CREATE", description = "Contest를 생성합니다.")  
@ApiResponses(value = {  
        @ApiResponse(responseCode = "201", description = "Contest를 생성했습니다",  
                content = @Content(schema = @Schema(implementation = ContestResponseDto.class),  
                        mediaType = "application/json")),  
        @ApiResponse(responseCode = "400", description = "요청한 입력값이 지정된 검증을 실패했습니다.",  
                content = @Content(schema = @Schema(implementation = ErrorResponse.class),  
                        mediaType = "application/json")),  
        @ApiResponse(responseCode = "401", description = "액세스 토큰이 없습니다",  
                content = @Content(schema = @Schema(implementation = ErrorResponse.class),  
                        mediaType = "application/json")),  
        @ApiResponse(responseCode = "403", description = "접근 권한이 없는 사용자입니다.",  
                content = @Content(schema = @Schema(implementation = ErrorResponse.class),  
                        mediaType = "application/json")),  
        @ApiResponse(responseCode = "409", description = "시작시간이 종료시간보다 뒤에 있습니다.",  
                content = @Content(schema = @Schema(implementation = ErrorResponse.class),  
                        mediaType = "application/json"))  
})  
public ResponseEntity<ContestResponseDto> createContest(  
        @RequestBody @Validated ContestRequestDto contestRequestDto) {  
  
    return ResponseEntity.created(URI.create(""))  
            .body(contestCRUDService.createContest(contestRequestDto));  
}

Swagger 문서코드와 프로덕션 코드가 합쳐져서 코드 가독성이 떨어집니다.
그렇다고 Swagger 문서코드를 포기할 수는 없습니다.
따라서 둘이 공존할 수 있는 방법을 찾아야합니다

해결방법

해결방법은 인터페이스를 활용하는 것입니다.
인터페이스에 Swagger 문서코드만 포함하고, 구현체에 실제 프로덕션 코드를 유지하는 것입니다

@Operation(summary = "Schedule Page GET", description = "일정 페이지 데이터를 조회합니다.")  
@ApiResponses(value = {  
        @ApiResponse(responseCode = "200", description = "일정 페이지 데이터 조회 성공",  
                content = @Content(array = @ArraySchema(schema =  
                @Schema(implementation = EventResponseDto.class)),  
                        mediaType = "application/json"),  
                headers = {@Header(name = "etag",  
                        description = "\"etagexample\"과 같은 형태로 제공됩니다. If-None-Match속성에 Etag를 추가해서 요청하세요"),  
                        @Header(name = "Cache-Control",  
                                description = "클라이언트 캐시 사용, 캐싱 최대유효시간 1시간, 유효시간 지난 후에는 반드시 서버로 재요청하세요")}),  
        @ApiResponse(responseCode = "304", description = "캐시 데이터의 변경사항이 없습니다. 로컬 캐시 데이터를 사용하세요",  
                content = @Content (mediaType = "None")),  
        @ApiResponse(responseCode = "400", description = "잘못된 HTTP 입력 요청",  
                content = @Content(schema = @Schema(implementation = ErrorResponse.class),  
                        mediaType = "application/json"))  
})  
ResponseEntity<List<EventResponseDto>> readStudentSchedule(  
        @Parameter(description = "Contest PK", example = "1")  
        Long contestId,  
        @Parameter(description = "조회할 페이지 번호", example = "1")  
        Integer offset,  
        @Parameter(description = "페이지당 조회할 데이터 개수", example = "1")  
        Integer limit  
);

위와 같이 인터페이스는 Swagger 문서 코드만 포함하고,

@GetMapping("public/contests/{contest}/schedules/v1")  
public ResponseEntity<List<EventResponseDto>> readStudentSchedule(  
        @PathVariable("contest")  
        Long contestId,  
        @RequestParam(value = "offset", required = false)  
        Integer offset,  
        @RequestParam(value = "limit", required = false)  
        Integer limit  
){  
    return ResponseEntity.ok(commonPageService  
            .readStudentSchedulePage(contestId, PageRequest.of(offset-1, limit)));  
}

구현체는 프로덕션 코드만 포함하도록 개선했습니다

마무리

문서와 코드의 가독성을 모두 챙기면서 기능을 유지하는 API문서화 작업을 완성했습니다
자세한 API문서 덕분에 이제 FE와의 불필요한 커뮤니케이션이 감소할 것입니다!

이번 정리로 상세한 API문서 작성의 중요성을 크게 배웠습니다.
실제로 프로젝트 개발도중, 기본 Swagger-UI 문서를 제공했을 때,
당연히 이해할 것이라고 생각한 내용을 FE가 이해하지 못해 추가 질문이 발생했습니다.
이러한 커뮤니케이션 비용이 반복해서 발생하다보니
API문서화 대신 개발에 집중한 시간보다 더 많은 지연시간이 발생했습니다.

이 과정에서 API 문서화의 중요성을 크게 배웠습니다.
FE가 이해하기 쉽고 활용하기 쉬운 API문서를 작성했다면 커뮤니케이션 비용이 발생하지 않았을 것입니다

앞으로는 API문서화 작업 시간을 낭비라고 생각하지 않고,
커뮤니케이션 비용을 줄이는 합리적인 선택으로 생각으로 임할 것입니다

참고:

• springdoc-openapi 공식문서
• Swagger 참고