[OAS] Swagger Codegen 필요성 (With. Spring Boot)

📗 설계 우선 접근 방식을 적용하기 위한 OAS!

설계 우선 접근 방식(Design-First Approach)은 API 개발 과정에서 API의 설계를 먼저 정의하고, 이를 기반으로 구현을 진행하는 방법론이다. 이 접근 방식은 API의 명확한 정의와 문서화를 통해 개발자 간의 커뮤니케이션을 원활하게 하고, API의 일관성과 품질을 높이는 데 중점을 둔다.

 

OpenAPI Specification(OAS)은 RESTful API를 명확하게 정의하고 문서화하기 위한 표준화된 형식이다. OAS는 API의 엔드포인트, HTTP 메서드, 요청 및 응답 형식, 데이터 모델 등을 JSON 또는 YAML 형식으로 기술할 수 있게 해준다. OAS는 API의 설계, 개발, 테스트, 문서화, 유지보수 등 다양한 단계에서 활용될 수 있으며, API의 일관성과 품질을 높이는 데 중요한 역할을 한다.

 

설계 우선 접근 방식과 OAS는 API 개발 과정에서 서로를 보완하는 역할을 한다. 설계 우선 접근 방식은 API의 구조와 동작을 명확하게 정의하고, 이를 통해 개발자와 이해관계자 간의 커뮤니케이션을 원활하게 한다. OAS는 이러한 정의를 표준화된 형식으로 문서화하고, 이를 통해 API의 일관성과 품질을 높일 수 있다. 이 두 가지를 결합하면 API 개발의 효율성과 품질을 크게 향상시킬 수 있다.

 

📗 Swagger Codegen?

Swagger Codegen은 OpenAPI Specification(OAS) 문서를 기반으로 다양한 프로그래밍 언어와 프레임워크에 맞는 클라이언트 SDK, 서버 스텁, 문서 등을 자동으로 생성하는 도구이다. Spring Boot와 결합하여 Swagger Codegen을 사용하면 다음과 같은 이점을 얻을 수 있다.

1. 자동화된 서버 스텁 생성

Swagger Codegen을 사용하면 OpenAPI 문서를 기반으로 Spring Boot 서버 스텁을 자동으로 생성할 수 있다. 이를 통해 개발자는 반복적이고 시간이 많이 소요되는 작업을 자동화할 수 있다. 서버 스텁은 API 엔드포인트의 기본 구조를 제공하므로, 개발자는 비즈니스 로직에 집중할 수 있다.

2. 일관된 API 문서화

OpenAPI Specification은 API를 명확하게 문서화하는 표준이다. Swagger Codegen을 사용하면 OpenAPI 문서를 기반으로 일관된 API 문서를 생성할 수 있다. 이를 통해 개발자와 사용자 모두 API를 쉽게 이해하고 사용할 수 있다. 또한, API 문서와 실제 구현 간의 불일치를 줄일 수 있다.

3. 빠른 프로토타이핑

Swagger Codegen을 사용하면 API의 프로토타입을 빠르게 생성할 수 있다. 이를 통해 개발자는 API 설계를 빠르게 검증하고 피드백을 받을 수 있다. 또한, 초기 개발 단계에서 API의 구조와 동작을 쉽게 테스트할 수 있다. Spring Boot와 결합하여 빠르게 실행 가능한 프로토타입을 만들 수 있다.

4. 유지보수 용이성

Swagger Codegen을 사용하면 API 문서와 코드가 항상 동기화된 상태를 유지할 수 있다. API가 변경될 때마다 OpenAPI 문서를 업데이트하고 Swagger Codegen을 다시 실행하면 최신 상태의 서버 스텁을 생성할 수 있다. 이를 통해 유지보수가 용이해지고, 코드와 문서 간의 불일치를 줄일 수 있다.

5. 협업 향상

Swagger Codegen을 사용하면 개발자, QA, 문서 작성자 등 다양한 팀 구성원 간의 협업이 향상된다. OpenAPI 문서를 기반으로 자동 생성된 코드와 문서를 통해 팀 구성원들이 API의 동작을 명확하게 이해할 수 있다. 이를 통해 커뮤니케이션이 원활해지고, 개발 과정에서 발생할 수 있는 오류를 줄일 수 있다.

6. 테스트 자동화

Swagger Codegen을 사용하면 API 테스트를 자동화할 수 있다. 자동 생성된 클라이언트 SDK를 사용하여 API 테스트 스크립트를 작성하고, 이를 통해 API의 동작을 검증할 수 있다. 이를 통해 테스트 커버리지를 높이고, API의 안정성을 보장할 수 있다.

7. 다양한 언어 및 프레임워크 지원

Swagger Codegen은 다양한 프로그래밍 언어와 프레임워크를 지원한다. 이를 통해 개발자는 자신이 사용하는 언어와 프레임워크에 맞는 클라이언트 SDK나 서버 스텁을 생성할 수 있다. 예를 들어, Spring Boot 서버 스텁을 생성하는 것 외에도 JavaScript, Python, Ruby 등 다양한 언어에 맞는 클라이언트 SDK를 생성할 수 있다.

8. 표준화된 API 설계

OpenAPI Specification을 사용하여 API를 설계하면 표준화된 방식으로 API를 정의할 수 있다. 이를 통해 API의 일관성을 유지하고, 다른 개발자나 팀과의 협업이 용이해진다. Swagger Codegen은 이러한 표준화된 API 설계를 기반으로 코드를 생성하므로, API의 품질을 높일 수 있다.

9. 개발 속도 향상

Swagger Codegen을 사용하면 많은 수작업을 자동화할 수 있으므로 개발 속도가 향상된다. Spring Boot와 결합하여 빠르게 서버 스텁을 생성하고, 이를 기반으로 비즈니스 로직을 구현할 수 있다. 이를 통해 개발자는 더 빠르게 기능을 구현하고, 제품 출시 시간을 단축할 수 있다.

 

이와 같이 Spring Boot에서 Swagger Codegen을 사용하면 자동화된 코드 생성, 일관된 API 문서화, 빠른 프로토타이핑, 유지보수 용이성, 협업 향상, 테스트 자동화, 다양한 언어 및 프레임워크 지원, 표준화된 API 설계, 개발 속도 향상 등 여러 가지 이점을 얻을 수 있다. 이를 통해 개발자는 API 개발의 효율성을 높이고, 품질을 향상시킬 수 있다.

REFERENCE

https://swagger.io/docs/open-source-tools/swagger-codegen/codegen-v3/about/

https://swagger.io/blog/code-first-vs-design-first-api/

https://www.baeldung.com/spring-boot-openapi-api-first-development