🔙뒤로가기

REST API와 Swagger

REST (Representational State Transfer)는 웹 서비스를 구축하고 사용하는데 널리 채택되는 아키텍처 스타일이다. REST는 표준 HTTP 메서드를 사용하여 웹 리소스를 생성, 읽기, 업데이트, 삭제(CRUD)하는 것을 기반으로 한다. RESTful API는 이러한 REST 원칙을 따르는 웹 서비스 API를 의미한다.

Swagger는 RESTful API를 위한 프레임워크로, API의 설계, 빌드, 문서화 및 테스트를 쉽게 할 수 있게 해준다.

Swagger와 REST API의 상호작용

1. API 설계
   • Swagger에서는 YAML이나 JSON 형식을 사용하여 REST API를 시각적으로 설계할 수 있음.
   • API 엔드포인트, 요청/응답 형식, HTTP 메서드, 오류 메시지 등을 정의하고 표현할 수 있음.
2. API 문서화
   • Swagger를 사용하면, API의 모든 엔드포인트와 메서드, 그리고 각 엔드포인트에서 예상되는 요청과 응답에 대한 자세한 정보를 자동으로 문서화할 수 있음.
   • 이 문서는 Swagger UI를 통해 웹에서 쉽게 탐색하고 읽을 수 있음.
3. API 테스트
   • Swagger UI를 통해 사용자는 웹 브라우저에서 직접 API 호출을 보내고 응답을 확인할 수 있음.
   • 이는 개발자가 API의 실제 동작을 빠르게 테스트하고 검증할 수 있게 해줌.

Swagger Specification

Swagger Specification(혹은 OpenAPI Specification)은 RESTful API를 설계, 빌드, 문서화, 그리고 시각화하기 위한 강력한 언어-agnostic(특정 언어에 종속되지 않는) 규격임.

OpenAPI 명세서는 다음과 같은 정보를 담고 있음:

1. API의 일반적인 정보: API의 제목, 설명, API의 버전, API의 host (기본 URL), API가 지원하는 경로, API의 접근 제한 등과 같은 기본 정보를 포함하고 있음.
2. API의 엔드포인트: API가 제공하는 모든 경로와 해당 경로에서 사용 가능한 HTTP 메소드(GET, POST, PUT, DELETE 등)를 나열함.
3. 각 엔드포인트의 작동 방식: 각 엔드포인트에서 예상되는 요청과 응답, 각 요청에 대한 예상 응답 코드와 해당 메시지, 사용 가능한 매개변수와 이들이 필수인지 아닌지, 매개변수가 어디에서 사용되는지(경로, 쿼리, 헤더, 바디 등) 등에 대한 정보를 제공함.
4. 객체 정의: API 응답에서 반환될 수 있는 객체와 그 프로퍼티에 대한 정의를 제공함. 이는 API의 요청과 응답 형식을 명확하게 이해하는 데 도움이 됨.

Swagger Specification은 YAML 또는 JSON 형식으로 작성될 수 있으며, 이는 개발자들이 쉽게 읽고 쓸 수 있는 형식이다. 또한 이 규격에 따라 작성된 문서는 Swagger UI를 통해 사람이 읽을 수 있는 형태의 동적인 문서로 변환될 수 있다. 이를 통해 API의 사용자는 API에 대한 깊은 이해 없이도 API의 작동 방식을 쉽게 이해하고 테스트할 수 있다.

Swagger Tools Overview

Swagger는 RESTful API를 디자인하고, 빌드하고, 문서화하고, 사용하기 위한 여러 도구들을 제공한다. 주요 Swagger 도구들은 다음과 같다

1. Swagger Editor
   • 웹 기반 편집기
   • API를 정의하고 Swagger 또는 OpenAPI 명세에 따라 문서를 작성하고 테스트할 수 있게 해줌.
   • Editor는 실시간으로 변경사항을 반영하고 문법 오류를 검사해줌.