API 문서화 도구 : Swagger (장점보단 단점이 많아 Spring Rest Docs 적용을 많이하네요...)

Rest API 문서화 관련 Swagger를 사용한다는 이야기를 듣고, 바로 Swagger 찍먹 시작!

1개의 의존성 추가하고, Swagger 설정관련 Bean 만들어주니 완성!!

의존성 추가

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

Open API Bean 설정

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI api() {
        return new OpenAPI().
                .paths(new Paths().addPathItem("address", new PathItem()))
                .info(new Info()
                .title("API 메인 타이틀 : 주소 검색 API")
                .description("API 상세 설명: 외부 API 문서 모음")
                .version("1.0.0"));
    }
}

10분도 걸리지 않아 "와 이거 신세계당!!" 이러고 좋아했는데,
각 API별 설명을 조금 추가하니, 설명 Annotation 때문에 코드라인이 확 늘어나더라구요. (아래 예시코드 참고)

@GetMapping("/gets")
@Operation(summary = "Get member profile")
@ApiResponses(value = { @ApiResponse(responseCode = "200", description = "성공", content = {@Content(schema = @Schema(implementation = Keyword.class))}),
@ApiResponse(responseCode = "404", description = "검색결과 없음.")})
@Tag(name = "Address", description = "행안부 주소검색 api에 keyword 검색기능을 제공 <br>" 
            "행안부 주소검색 api에 keyword 검색기능을 제공 <br>" +
            "qkqhdi")
    public ResponseEntity<String> clientGetMethod(
    
    .... 이하 생략 ....

@Annotation없이 상세설명을 다른 형식, 이를테면 .yaml 등등... 없나 봤는데... 그런건 존재 하지 않나봐요 :(또르르

마켓 컬리 테크 블로그 글 보기

다른 방법을 찾다가 발견한 마켓 컬리 테크 블로그!!!
위 글을 쓰신 컬리의 개발자님은 Swagger Annotation의 운영코드 침투 라고 표현하셨던데...
너무나 공감됐어요...

Swagger 적용 시 간단한 API 문서만 필요한 경우 의존성 주입과 Configuration Bean만 추가하면 됨.
그러나 상세설명을 추가하기 위해서는 Annotation은 필수적임!

결국 단순한 수준의 API 문서화는 Swagger를 쓰면 좋겠지만
자세한 API 문서화를 원한다 Annotation으로 코드가 길어져 실제코드에서 가독성이 떨어지는 부작용이 생기게 됨을 알게되었습니다.

다음 포스팅은 마켓컬리 개발자님 Test코드 클론코딩 후기로 돌아올게요!

+++ 2024.03.22 추가
우아한테크 Spring Rest Docs에 대한 글 보기