[Spring Boot] Swagger vs Spring REST Docs, Swagger API 문서 자동화

사실 Spring REST Docs와 Swagger 두가지 중 고민하다가 Swagger로 일단 설정했다. 일단 아래 차이를 보자

 

Swagger (OpenAPI)

1. 자동화된 문서 생성:
   • Swagger는 API 스펙을 작성하면 문서를 자동으로 생성해 줍니다. 이를 통해 API의 모든 엔드포인트, 요청 및 응답의 구조, 데이터 타입 등을 자동으로 문서화할 수 있습니다.
   • 코드와 독립적으로 작성되거나, 애노테이션을 통해 코드에서 직접 스펙을 추출할 수도 있습니다.
2. 인터랙티브 문서:
   • Swagger는 인터랙티브한 문서를 제공합니다. 개발자나 사용자들은 Swagger UI를 통해 API를 테스트해볼 수 있으며, 각 엔드포인트에 대한 예시 요청을 쉽게 만들 수 있습니다.

Spring REST Docs

1. 코드 기반 문서화:
   • Spring REST Docs는 API 문서를 코드와 함께 유지할 수 있도록 해줍니다. 이는 테스트를 기반으로 하여 문서를 생성하며, 테스트가 성공적으로 통과한 엔드포인트만 문서화됩니다.
   • 주로 Spring 프레임워크와 함께 사용됩니다.
2. 정적 문서:
   • Spring REST Docs는 주로 정적인 문서를 생성합니다. 이는 JSON 스니펫과 같은 샘플 데이터를 포함하며, 사용자 정의가 용이합니다.
   • 인터랙티브한 기능은 없지만, Markdown, AsciiDoc, HTML 등 다양한 형식으로 문서를 생성할 수 있습니다.
3. 테스트 주도 문서화:
   • 테스트 코드가 문서의 출발점이 되므로, 코드가 업데이트되면 문서도 자동으로 업데이트됩니다. 이로 인해 문서와 코드 간의 일관성을 유지할 수 있습니다.

이런 차이가 있는데 사실 핵심은 TDD기반의 설계는 무조건 Spring REST Docs를 사용하는게 맞다고 생각한다. 왜냐면 test코드를 작성하지 않으면 문서를 못만들기 때문이다. 또한 개발자들이 선호하는 이유는 원본코드를 건들이지 않고 test코드에 작성함으로서 더럽히지 않는다는 큰 장점이 있다.

하지만 단점은 test를 작성하지 않으면 사용하지 못하고 개인적으로 Swagger보다 쓰기 어려운 것 같다. 

 

일단 난 TDD 신봉자가 아님으로 구현을 어느정도 끝낸뒤 적용하고자 우선 Swagger을 도입하고자 한다. 나중에 Test 코드를 전부 작성하게 되면 REST Docs로 다시한 번 정리를 해보겠다.

 

우선 의존성을 설치한다.

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

 

그런 뒤 SwaggerConfig.class를 작성한 후 아래와 같은 설정을 해준다.

 

• JWT를 사용하지 않는 경우

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .components(new Components())
                .info(apiInfo());
    }

    private Info apiInfo() {
        return new Info()
                .title("API Test") // API의 제목
                .description("Let's practice Swagger UI") // API에 대한 설명
                .version("1.0.0"); // API의 버전
    }
}

• JWT를 사용하는 경우

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI openAPI() {
        String jwt = "JWT";
        SecurityRequirement securityRequirement = new SecurityRequirement().addList(jwt);
        Components components = new Components().addSecuritySchemes(jwt, new SecurityScheme()
                .name(jwt)
                .type(SecurityScheme.Type.HTTP)
                .scheme("bearer")
                .bearerFormat("JWT")
        );
        return new OpenAPI()
                .components(new Components())
                .info(apiInfo())
                .addSecurityItem(securityRequirement)
                .components(components);
    }
    private Info apiInfo() {
        return new Info()
                .title("API Test") // API의 제목
                .description("Let's practice Swagger UI") // API에 대한 설명
                .version("1.0.0"); // API의 버전
    }
}

 

 

그러면 각 컨트롤마다 자동으로 아래와 같은 명세서가 생기게 된다. 

 

나같은 경우에도 원본 코드를 더럽히고 싶지 않기 때문에 추가 설정은 안해주었다. 

이 이후에 몇가지 태그로 설정을 할 수 있는데

 

1. @Operation 어노테이션

@Operation 어노테이션은 특정 엔드포인트에 대한 세부 정보를 설정하는 데 사용됩니다. 이 어노테이션을 사용하면 엔드포인트의 설명, 응답 코드, 요청 파라미터 등을 정의할 수 있습니다.

 

2. @Tag 어노테이션

@Tag 어노테이션은 엔드포인트를 그룹화하는 데 사용됩니다. 여러 엔드포인트를 공통 주제나 기능별로 묶어 더 쉽게 문서를 탐색할 수 있습니다.

 

사용법은 아래와 같다.

@RestController
@Tag(name = "Product Management", description = "Product 관련 API")
public class ProductController {

    @GetMapping("/products")
    @Operation(summary = "Get all products", description = "모든 제품을 반환합니다.", tags = {"Product Management"})
    public List<Product> getAllProducts() {
        // 제품 목록 반환 로직
    }
}

 

이거보다 더 많은 어노테이션이 있으나 너무 코드가 더러워져 더욱 자세한 명세서를 작성하기 위해선 REST Docs를 쓰는게 용이 할 듯 하다.

 

 예) @ApiResponse: API 엔드포인트의 다양한 응답 코드와 설명을 문서화하기 위해 사용됩니다.

 

 

ref

https://velog.io/@gmlstjq123/SpringBoot-%ED%94%84%EB%A1%9C%EC%A0%9D%ED%8A%B8%EC%97%90-Swagger-UI-%EC%A0%81%EC%9A%A9%ED%95%98%EA%B8%B0

SpringBoot 프로젝트에 Swagger UI 적용하기