API 문서 자동화: Swagger와 Spring REST Docs의 특징과 장단점

1. Swagger (특징, 장점, 단점, 작동 방식)

• 특징:
  • Swagger는 OpenAPI Specification (OAS)에 기반하여 API 문서화와 다른 도구들과의 통합을 지원한다.
  • 자동으로 API 엔드포인트를 탐색하여 문서를 생성하며, UI를 통해 API를 시험할 수 있다.
  • API의 구조, 요청/응답 형식, 상태 코드, 오류 메시지 등을 시각적으로 표시한다.
• 장점:
  • 쉬운 세팅 및 사용.
  • 눈에 띄는 UI.
  • 실제 API 호출 기능 제공.
• 단점:
  • 코드에 주석을 기반으로 하므로, 실제 코드와 문서화 사이에 불일치가 발생할 수 있다.
  • 실제 코드와 동기화를 위해 추가 작업이 필요할 수 있다.
• 작동 방식:
  • Swagger는 주로 코드나 주석에 기반하여 API 문서를 자동 생성한다.

 

2. Spring REST Docs (특징, 장점, 단점, 작동 방식)

• 특징:
  • 테스트 기반으로 문서를 생성합니다. 즉, 실제 코드의 테스트를 통과한 API만 문서화된다.
  • Asciidoctor나 Markdown 형식으로 문서를 생성하므로, 다양한 형식으로 출력 가능하다.
• 장점:
  • 테스트 기반으로 문서를 생성하므로, 문서와 코드의 불일치 가능성이 줄어듭니다.
  • 높은 신뢰도의 문서 제공.
• 단점:
  • 세팅 및 사용이 다소 복잡할 수 있다.
  • 테스트 코드 작성에 투자해야 하는 시간과 노력이 필요하다.
• 작동 방식:
  • 실제 테스트를 통과한 API에 대해서만 문서를 생성한다.
  • 즉, 작성한 테스트가 성공적으로 통과할 때만 문서화가 이루어진다.

 

3. 대중성과 사용률:

• Swagger: 빠른 시각화 및 쉬운 세팅 때문에 초기 프로토타이핑 및 개발에서 많이 사용된다.
• Spring REST Docs: 특히 테스트 주도 개발(TDD)을 선호하는 개발자나, 코드와 문서의 일치를 중요하게 생각하는 회사에서 선호된다.

 

4. Swagger 사용 예제:

Spring Boot, Swagger 2 사용

1. Gradle dependency:

implementation 'io.springfox:springfox-swagger2:2.9.2'   
implementation 'io.springfox:springfox-swagger-ui:2.9.2'

2. Swagger Configuration

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

3. Controller

@RestController
@RequestMapping("/api/greetings")
public class GreetingController {

    @GetMapping
    public ResponseEntity<String> getGreeting() {
        return ResponseEntity.ok("Hello, Swagger!");
    }
}

4. URL 접속
/swagger-ui.html

 

5. Spring REST Docs 사용 예제:

Spring Boot, JUnit 5, Spring REST Docs 사용

1. Gradle dependency:

testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'

2. Test

@WebMvcTest(GreetingController.class)
@AutoConfigureRestDocs(outputDir = "target/snippets")
public class GreetingControllerTest {

    @Autowired private MockMvc mockMvc;

    @Test public void shouldReturnDefaultGreeting() throws Exception {
        this.mockMvc.perform(get("/api/greetings"))
            .andExpect(status().isOk())
            .andDo(document("get-greeting"));
    }
}

3. Controller

 

@RestController
@RequestMapping("/api/greetings")
public class GreetingController {

    @GetMapping
    public ResponseEntity<String> getGreeting() {
        return ResponseEntity.ok("Hello, REST Docs!");
    }
}

4. 테스트 실행

결과 확인 : target/snippets/get-greeting 디렉토리 아래에 문서의 스니펫들이 생성됨

 

6. 선택시 고려해야 할 포인트와 특징:

1. Swagger (OpenAPI):
   • 자동화된 문서화: Swagger는 코드나 주석을 기반으로 자동으로 API 문서를 생성한다.
   • UI 제공: Swagger UI를 통해 사용자 친화적인 웹 인터페이스를 제공하며, 여기서 실제 API 요청을 보낼 수도 있다.
   • 확장성: 플러그인 및 여러 라이브러리와의 통합이 용이하다.
   • 주석 기반: 일부 개발자들은 API 문서화를 위해 주석을 작성하는 것을 번거롭게 생각할 수 있다. 또한 코드 변경 시 주석도 업데이트 해야 한다.
   • 표준화: OpenAPI Specification (OAS)을 따르므로, 다양한 툴과의 호환성이 좋다.
2. Spring REST Docs:
   • 테스트 기반 문서화: 실제로 수행되고 통과된 테스트 케이스를 기반으로 문서가 생성된다. 이로 인해 문서와 코드 사이의 불일치 가능성이 낮아진다.
   • 커스텀 문서화: Asciidoctor나 Markdown 등을 사용하여 상세한 문서를 작성할 수 있다.
   • 테스트와의 통합: 문서가 API의 테스트와 밀접하게 연결되어 있으므로, API 변경 시 테스트 실패로 인해 문서 업데이트를 바로 인지할 수 있다.
   • 입문 장벽: Swagger에 비해 초기 설정과 학습 곡선이 다소 높을 수 있다.
   • 정확성: 문서가 항상 최신 상태를 유지하며, API의 정확한 동작을 반영한다.
3. 결정 요인:
   • 신뢰성: API의 동작과 문서 사이의 불일치를 최소화하려는 경우 Spring REST Docs를 선호할 수 있다.
   • 편의성 및 속도: 빠르게 API 문서를 생성하고 사용자에게 제공하려는 경우 Swagger가 더 나을 수 있다.
   • 프로젝트의 복잡성: 복잡한 프로젝트에서는 테스트 기반의 문서화 방식이 더 안정적일 수 있다.

 

7. 참고 사이트:

1. 우아한 기술 블로그
2. hudi.blog