2024-05-23 오늘의 TIL

Swagger란

Swagger는 RESTful API를 설계, 빌드, 문서화 및 소비하기 위한 오픈 소스 소프트웨어 프레임워크 즉, 애플리케이션의 RESTful API 문서를 자동으로 구성하는 특수 도구라고 할수 있으며 Web API 문서화를 위한 도구입니다.

API 개발자에게는 API 정의를 작성하고, 문서화를 자동화하며, 클라이언트 SDK를 생성하는 등의 기능을 제공합니다. Swagger는 OpenAPI 사양(이전에는 Swagger 사양으로 알려짐)을 사용하여 API를 정의한다. 이 사양은 API의 엔드포인트, 요청 및 응답 구조, 인증 방법 등을 표준화된 방식으로 기술합니다.

왜 나왔을까

만약 웹개발자가 개발을 시작할 때 Web API가 만들어질 때까지 기다린다면 작업이 상당히 느려질 수 있다.

Web API를 만드는 개발자와 Web API를 사용하는 사람 간에 미리 명세를 정의하고 공유할 수 있다면 개발이 상당히 편리해지지 않을까?

그래서 나온 도구 중에 하나가 "스웨거"라고 할수 있다.

장점

• 자동화된 문서화: Swagger를 사용하면, API 엔드포인트, 요청/응답 형식 등을 자동으로 문서화할 수 있어, 수동으로 문서를 작성하는 시간을 절약할 수 있습니다.

• 인터랙티브한 API 문서: Swagger UI는 사용자들이 API를 시각적으로 탐색하고 테스트할 수 있는 인터페이스를 제공합니다. 이를 통해 개발자와 사용자가 API를 쉽게 이해하고 사용할 수 있습니다.

• 클라이언트 SDK 생성: Swagger Codegen을 사용하면, 다양한 프로그래밍 언어용 클라이언트 SDK를 자동으로 생성할 수 있어, API 소비자가 더 쉽게 API를 통합하고 사용할 수 있습니다.

• 표준화: OpenAPI 사양을 사용하여 API를 정의함으로써, API 정의의 표준화를 통해 일관성과 호환성을 보장할 수 있습니다.

동작원리

Swagger는 기본적으로 OpenAPI 사양을 중심으로 동작합니다. OpenAPI 사양은 API의 구조를 기술하는 표준 형식으로, Swagger 도구들이 이를 해석, 문서화하고, 코드를 생성한다. Spring Boot와 같은 프레임워크에서는, 어노테이션을 통해 API 엔드포인트를 정의하고, 이 정의를 바탕으로 Swagger가 자동으로 API 문서를 생성한다.

회고

스웨거(Swagger)에 대해서 알아볼 수 있는 시간이였고
어떻게 굴릴지는 다음 게시물에서 java spring으로 다뤄보는 시간을 가지도록 하겠다.