[Spring Boot] Swagger와 OpenAPI

Swagger와 OpenAPI란?

Swagger

Swagger는 RESTful API를 설계, 문서화, 그리고 테스트할 수 있는 도구 모음임.

• 개발자가 REST API를 쉽게 이해하고, 활용할 수 있도록 문서와 테스트 환경을 제공함.

• Swagger는 OpenAPI의 초기 버전(2.0)에서 시작되었으며, 이후 OpenAPI로 발전했음.

 

OpenAPI

OpenAPI는 API의 설계와 문서화를 위한 표준 사양임.

• OpenAPI Specification(OAS): RESTful API를 정의하는 문법 및 규칙.

• YAML 또는 JSON 형식으로 API의 엔드포인트, 요청/응답, 데이터 구조 등을 명세함.

---

Swagger와 OpenAPI의 관계

• Swagger는 OpenAPI Specification(OAS)의 초기 구현체였음.

• 현재 OpenAPI는 독립된 표준으로 관리되며, Swagger는 OpenAPI를 사용하는 도구 중 하나로 자리 잡았음.

---

Swagger의 주요 구성요소

 

1. Swagger UI

• API 문서를 웹 페이지 형태로 시각화함.

• API 요청을 직접 테스트할 수 있는 인터페이스를 제공함.

 

2. Swagger Editor

• OpenAPI 사양 문서를 작성할 수 있는 웹 기반 편집기.

• YAML 형식으로 OpenAPI 문서를 생성하고 검증함.

 

3. Swagger Codegen

• OpenAPI 명세서를 기반으로 클라이언트 SDK와 서버 스켈레톤 코드를 자동 생성함.

 

4. Swagger Hub

• API 설계와 문서화를 위한 협업 플랫폼.

• 팀원 간의 API 작업을 공유하고 관리할 수 있음.

---

OpenAPI Specification 주요 요소

 

1. 기본 구조

openapi: 3.0.0
info:
  title: Example API
  description: Example API for demonstration
  version: "1.0.0"
servers:
  - url: https://api.example.com
paths:
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: OK

 

2. 주요 필드

  1. openapi: OpenAPI 버전 명시 (예: 3.0.0).

  2. info: API 정보(title, description, version 등).

  3. servers: API가 동작하는 서버 URL.

  4. paths: API 엔드포인트 및 HTTP 메서드 정의.

  5. components: 공통 스키마, 보안 스키마 등을 정의.

---

Swagger를 Spring Boot에 적용하기

1. 의존성 추가

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.15</version>
</dependency>

 

2. Swagger UI 확인

 

• Spring Boot 애플리케이션 실행 후, /swagger-ui.html로 접속하면 Swagger UI 화면이 나타남.

---

Swagger와 OpenAPI의 장점

1. 자동 문서화

• API를 코드와 함께 유지 관리하며 자동으로 문서를 생성함.

 

2. 테스트 편리성

• Swagger UI를 통해 API 요청을 바로 테스트 가능.

 

3. 표준화된 설계

• OpenAPI를 통해 API 설계와 개발이 체계적으로 이루어짐.

 

4. 다양한 도구 지원

• Swagger Codegen, Swagger Hub 등을 통해 생산성을 높일 수 있음.

 

 

 

 

출처 : ChatGPT