Swagger 2 와 Swagger 3의 차이점 알아보기

Swagger 2 와 Swagger 3의  차이점 알아보기

 

Swagger는 API 문서를 자동화하고 시각화하기 위한 도구입니다. 

Swagger 2와 Swagger 3 (OpenAPI 3)는 주로 스펙 및 기능 차이에 대한 업데이트가 있습니다.

 이 차이점을 간략하게 살펴보겠습니다.

스펙 버전

Swagger 2는 Swagger 스펙 2.0을 따릅니다.
Swagger 3 (OpenAPI 3)는 OpenAPI 스펙 3.0.x를 따릅니다.

 

구조 변경

Swagger 3에서 구조와 속성 이름이 변경되어 더 명확하고 간결해졌습니다.

 

새로운 데이터 유형 및 스키마

Swagger 3에서는 oneOf, anyOf, not 등의 추가 스키마 키워드를 사용할 수 있습니다. 이를 통해 API에서 다양한 유형의 데이터를 더 잘 정의할 수 있습니다.

 

쿠키 인증 지원

Swagger 3 (OpenAPI 3)는 쿠키 기반 인증을 직접 지원합니다.

 

예제 추가

Swagger 3에서는 스키마에 여러 예제를 추가할 수 있습니다. 이를 통해 사용자에게 더 나은 API 설명을 제공할 수 있습니다.

 

서버 객체

Swagger 3에서는 호스트, 기본 경로, 스키마를 대체하는 새로운 서버 객체가 도입되었습니다. 이를 통해 API를 서비스하는 여러 서버를 정의할 수 있습니다.

 

Linking and Callbacks:

Swagger 3에서는 링크 및 콜백 기능이 도입되어, API 간의 관계와 웹훅에 대한 정의를 추가할 수 있습니다.
그러나 참고로, 이러한 차이점 때문에 Swagger 2와 Swagger 3 (OpenAPI 3) 문서는 서로 호환되지 않습니다. 

따라서 이전 버전에서 새 버전으로 마이그레이션하려면 문서를 업데이트해야 합니다.

 

---

Spring Boot 프로젝트에서 Swagger 3를 사용하려면 다음 의존성을 사용해야 합니다.

 

<dependencies>
  <!-- ... -->
  <dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.5.13</version>
  </dependency>
</dependencies>

 

dependencies {
  // ...
  implementation 'org.springdoc:springdoc-openapi-ui:1.5.13'
}