[Spring] Swagger를 사용하기 위한 여정

Spring boot로 제작한 프로젝트의 마무리 단계에서 swagger를 활용해 OpenAPI를 작성해 보려고 한다. OpenAPI에 대해 찾아보려니 헷갈리는 부분에 대해 명확히 짚고 넘어가고자 한다.

OpenAPI VS Open API

이 두 용어는 공백 한끗차이이다. 하지만 전혀 다른 뜻을 가지고 있으며 앞으로 설명할 때 OpenAPI는 OAS: OpenAPI Specification 라고 말하겠다.
OAS는 RESTful API 기반으로 정의된 규칙에 맞게 API spec을 json이나 yaml 방식으로 표현하는 용어이다. 직접 소스코드나 문서를 보지 않고 서비스를 이해할 수 있다는 장점이 있다.
Open API는 개방된 API로 누구나 사용할 수 있도록 API의 엔드포인트를 개방해둔 것으로 누구나 해당 API를 요청하여 데이터를 제공 받을 수 있다.

Swagger2.0? Swagger3.0? OpenAPI3.0?

Swagger에 대해 찾아보면 version에 따라 부르는 이름들이 달라 헷갈린다. 왜그러냐하면 Swagger는 2010년대 초 Tam Wordink라는 사람이 Wordnik 기업 자체 API용 UI로 개발하였고 2015년 초에는 SmartBear라는 회사에서 Swagger를 인수하였다. 2015년 말에 OpenAPI Initiative에 Swagger를 기부하면서 OpenAPI Specification(OAS)로 이름이 변경되었다. 그래서 2.0을 표기할 때에는 "swagger": "2.0", 3.0을 표기할 때에는 "openapi": "3.0"이라고 한다. 즉, Swagger는 OAS를 작성하기 위한 하나의 tool이며 중간에 이러한 과정때문에 사람들이 많이들 혼용해서 사용하는 것 같다.

API는 무엇인가?

이제 계속해서 나오는 용어 API에 대해 자세히 알아보자. API는 Application Programming Interface로 다양한 애플리케이션과 서비스가 서로 소통하고 데이터를 교환하는 방식이다. 예를들면 프론트엔드 개발자와 백엔드 개발자가 서로 데이터를 주고 받을 때 사용하는 방식이 API이다. 특징으로는 다음과 같다.

• 추상화: 복잡한 내부 로직을 숨기고 간단한 인터페이스 제공
• 표준화: 일관된 방식으로 데이터 교환 가능
• 모듈성: 애플리케이션을 독립적인 모듈로 분리 가능
• 확장성: 기존 시스템에 새로운 기능 추가 용이

API의 종류

개발을 시작하기에 앞서 프론트엔드 개발자와 백엔드 개발자가 어떤 식으로 데이터를 주고 받을지 고민해볼 것이다. 우선 API의 종류에 대해 찾아보고 해당 프로젝트에 어울리는 API를 선택하면 될 것 같다.

1. REST API

REST (Representational State Transfer)는 HTTP 프로토콜을 기반으로 한 웹 API 디자인 패턴이다.

• 특징
  • 클라이언트-서버 구조
  • 무상태성 (Stateless)
  • 캐시 가능 (Cacheable)
  • 계층 구조 (Layered System)
• 예제 (JSON 기반 REST API 요청 및 응답)

  GET /users/1 HTTP/1.1
  Host: example.com
  Content-Type: application/json

  {
    "id": 1,
    "name": "홍길동",
    "email": "hong@example.com"
  }

2. SOAP API

SOAP (Simple Object Access Protocol)는 XML 기반의 프로토콜로, 주로 엔터프라이즈 시스템에서 사용된다.

• 특징
  • XML 형식의 메시지 교환
  • 높은 보안성과 트랜잭션 지원
  • HTTP, SMTP 등 다양한 프로토콜에서 동작 가능
• 예제 (SOAP 요청 및 응답)

  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
      <getUser>
        <id>1</id>
      </getUser>
    </soapenv:Body>
  </soapenv:Envelope>

  <soapenv:Envelope>
    <soapenv:Body>
      <getUserResponse>
        <name>홍길동</name>
        <email>hong@example.com</email>
      </getUserResponse>
    </soapenv:Body>
  </soapenv:Envelope>

3. GraphQL API

GraphQL은 Facebook에서 개발한 쿼리 언어로, 클라이언트가 원하는 데이터만 요청할 수 있는 유연한 API이다.

• 특징
  • 클라이언트가 필요한 데이터만 요청 가능
  • 단일 엔드포인트에서 다양한 데이터 조회 가능
  • 중첩된 데이터 요청이 용이함
• 예제 (GraphQL 쿼리 및 응답)

  query {
    user(id: 1) {
      name
      email
    }
  }

  {
    "data": {
      "user": {
        "name": "홍길동",
        "email": "hong@example.com"
      }
    }
  }

4. gRPC API

gRPC는 Google에서 개발한 고성능 원격 프로시저 호출(Remote Procedure Call) 프레임워크이다.

• 특징

  • 프로토콜 버퍼(Protocol Buffers, ProtoBuf)를 사용하여 직렬화
  • HTTP/2 기반의 빠른 통신
  • 양방향 스트리밍 지원

• 예제 (gRPC 서비스 정의 및 요청)

  syntax = "proto3";
  
  service UserService {
    rpc GetUser (UserRequest) returns (UserResponse);
  }
  
  message UserRequest {
    int32 id = 1;
  }
  
  message UserResponse {
    string name = 1;
    string email = 2;
  }

5. API 선택 기준

• 데이터 형식과 구조: REST는 JSON, SOAP는 XML, gRPC는 ProtoBuf를 사용함.
• 성능: REST는 HTTP 기반, gRPC는 HTTP/2 기반으로 속도가 더 빠름.
• 보안: SOAP는 높은 보안성을 제공하지만 무겁고, REST는 OAuth 같은 인증 방식을 활용함.
• 사용 편의성: GraphQL은 유연한 데이터 요청이 가능하나 학습 곡선이 있음.

API 설계

어떤 종류의 API를 사용할지 정했으면 프로젝트 구성원들과 함께 API 규칙을 정하여야 한다. 무작정 API 규칙을 정하는 것보다 각각의 API 설계 원칙에 고려하여 규칙을 작성하는 것이 현명한 판단이 될 것이다.

RESTful API 설계

REST에는 여섯가지의 기본 원칙이 있으며, 이 원칙을 준수한 인터페이스는 RESTful 하다고 표현한다.

1. Client–Server 구조

• 클라이언트와 서버는 서로 독립적으로 개발될 수 있어야 한다.
• 클라이언트는 오직 URI를 통해 리소스를 식별해야 하며, 서버의 내부 구현에 의존하지 않아야 한다.
• 인터페이스가 변경되지 않는 한, 클라이언트와 서버는 독립적으로 변경 및 대체될 수 있다.
• (관심사의 명확한 분리, Separation of Concerns)

2. Stateless (무상태성)

• 각 클라이언트 요청에는 요청을 처리하는 데 필요한 모든 정보가 포함되어야 한다.
• 서버는 클라이언트의 상태를 저장하지 않으며, 요청 간 세션 정보를 유지하지 않는다.
• 인증 및 인가 정보 또한 클라이언트가 관리하며, 각 요청 시 포함하여 서버에 전달해야 한다.

3. Cacheable (캐싱 가능)

• 서버는 Response cache-control 헤더를 활용하여 해당 응답이 캐싱 가능한지 여부를 제공해야 한다.
• 클라이언트는 캐싱 가능한 응답을 저장하여 서버와의 불필요한 요청을 줄이고 성능을 향상시킬 수 있다.
• 적절한 캐싱을 활용하면 서버의 부하를 줄이고 가용성을 높일 수 있다.

4. Uniform Interface (일관된 인터페이스)

REST는 시스템 전체를 단순화하고 가시성을 개선하기 위해 4가지 인터페이스 규칙을 정의한다.

1. Identification of Resources (자원의 식별)

   • 각 요청에서 개별 자원을 명확히 식별할 수 있어야 한다.
   • 예: GET /users/1 (ID가 1인 사용자를 조회)

2. Manipulation of Resources Through Representations (자원의 표현을 통한 조작)

   • 클라이언트는 적절한 표현과 메타데이터를 통해 서버가 자원을 변경, 삭제할 수 있도록 요청해야 한다.
   • 예: PUT /users/1 요청 시 사용자 정보를 JSON 형식으로 제공하여 수정 가능하게 함.

3. Self-Descriptive Messages (자체 설명적 메시지)

   • 메시지 자체에 요청을 어떻게 처리해야 하는지에 대한 정보가 포함되어야 한다.
   • 예: Content-Type 헤더를 활용하여 응답 데이터의 형식을 명확히 지정.

4. Hypermedia as the Engine of Application State (HATEOAS, 하이퍼미디어 기반 상태 전이)

   • 응답에는 단순한 데이터뿐만 아니라, 관련된 링크를 포함하여 상태 전이를 가능하게 해야 한다.
   • 예: GET /users/1 응답에 해당 사용자의 프로필 수정 링크 포함.

5. Layered System (다중 계층 구조)

• REST 아키텍처는 다중 계층을 지원하며, API 서버, 인증 서버, 데이터베이스 서버 등을 분리할 수 있다.
• 각 계층은 자신과 직접 통신하는 계층만을 인식하며, 전체 시스템의 구조를 알 필요가 없다.
• 클라이언트는 API 서버와만 통신할 수 있으며, 내부의 다른 계층(예: DB 서버)과 직접 상호작용할 수 없다.

6. Code on Demand (선택 사항)

• 서버는 클라이언트에서 실행할 수 있는 코드를 제공할 수 있다.
• 이를 통해 클라이언트가 사전에 구현해야 할 기능을 줄이고 확장성을 높일 수 있다.
• 예: JavaScript 코드 스니펫을 API 응답으로 제공하여 클라이언트에서 실행되도록 함.

블로그 API 설계

1. 리소스 정의

블로그 API에서 다룰 주요 리소스는 다음과 같다.

• 게시글 (posts)
• 댓글 (comments)
• 사용자 (users)
• 카테고리 (categories)

---

2. 엔드포인트 설계

RESTful 원칙을 따르는 엔드포인트는 아래와 같이 정의된다.

📝 게시글 관련

메서드	엔드포인트	설명
GET	/posts	모든 게시글 조회
GET	/posts/{id}	특정 게시글 조회
POST	/posts	새 게시글 작성
PUT	/posts/{id}	게시글 수정
DELETE	/posts/{id}	게시글 삭제

💬 댓글 관련

메서드	엔드포인트	설명
GET	/posts/{id}/comments	특정 게시글의 모든 댓글 조회
POST	/posts/{id}/comments	특정 게시글에 새 댓글 작성
PUT	/comments/{id}	댓글 수정
DELETE	/comments/{id}	댓글 삭제

👤 사용자 관련

메서드	엔드포인트	설명
GET	/users/{id}	특정 사용자 정보 조회
POST	/users	새 사용자 등록
PUT	/users/{id}	사용자 정보 수정
GET	/users/{id}/posts	특정 사용자의 모든 게시글 조회

🏷 카테고리 관련

메서드	엔드포인트	설명
GET	/categories	모든 카테고리 조회
GET	/categories/{id}/posts	특정 카테고리의 모든 게시글 조회

이러한 API 설계를 기반으로 블로그 서비스의 RESTful API를 구축할 수 있다.

마무리

Swagger로 OpenAPI를 작성하려다 보니 자연스럽게 REST API 설계까지 깊이 있게 공부하게 되었다. 결국 하나의 도구나 기술을 제대로 활용하려면 그에 필요한 배경 지식까지 폭넓게 이해해야 한다는 점을 다시금 깨달았다. 하지만 그만큼 API 설계를 더 확실하게 이해할 수 있었고, 왜 이렇게 설계해야 하는지에 대한 이유도 더욱 명확해졌다.

이번 학습을 통해 API에 대한 개념을 탄탄히 다질 수 있었고, 앞으로의 개발 과정에서도 더 체계적으로 API를 설계할 수 있을 것 같다.

출처

Swagger와 OpenAPI
API 설계
RESTful API