Swagger

 

일단 swagger를 이해하기 위해서 나동빈님의 유튜브 재생목록 swagger를 정주행.. 총 6편

https://www.youtube.com/watch?v=akbdsrOpQ60&list=PLRx0vPvlEmdAezo0wkmUdT6WBCch0_1ie

 

✅ 1. Swagger란?

Swagger는 REST API를 문서화하고 시각적으로 제공해주는 오픈소스 프레임워크.

• 요즘에는 Swagger의 후속 프로젝트인 OpenAPI 명세(OpenAPI Specification, OAS)를 기반으로 작동
• 대표 도구:
  • Swagger UI – API를 브라우저에서 테스트할 수 있는 인터페이스
  • Swagger Editor – 명세 작성용 웹 툴
  • Swagger Codegen – 명세 기반으로 클라이언트 코드 자동 생성

---

✅ 2. Swagger의 특징

🔍 API 자동 문서화	코드에 주석이나 어노테이션만 달면 자동으로 API 문서 생성
🧪 테스트 UI 제공	Swagger UI를 통해 브라우저에서 직접 API 호출 테스트
🔐 인증/헤더 지원	토큰 입력, 헤더 설정 등을 문서에서 바로 입력 가능
🔁 클라이언트 코드 생성	OpenAPI 명세 기반으로 다양한 언어용 API 코드 자동 생성
📄 YAML/JSON 기반	API 문서가 YAML/JSON 명세로 구성됨

 

 

✅ 3. Swagger와 연결된 구성도

Controller (@RestController + Swagger 어노테이션)
   ↓
Spring Boot (Swagger 설정 포함)
   ↓
Swagger Config → Swagger UI (http://localhost:8080/swagger-ui/index.html)

 

✅ 4. Spring Boot에서 Swagger 사용법

🔹 1) 의존성 추가 (Spring Boot 3.x 기준)

build.gradle

dependencies {
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'
}

 

🔹 2) Swagger 자동 문서화 어노테이션

@OpenAPIDefinition	전체 API에 대한 정보 설정 (제목, 버전 등)
@Operation	메서드에 대한 설명, 응답 코드 등
@Parameter, @RequestBody	파라미터, 바디에 대한 설명
@Tag	API 그룹 묶기

@RestController
@RequestMapping("/users")
@Tag(name = "User API", description = "사용자 관련 API입니다.")
public class UserController {

    @Operation(summary = "회원 조회", description = "ID로 회원 정보를 조회합니다.")
    @GetMapping("/{id}")
    public UserDto getUser(@PathVariable Long id) {
        ...
    }

    @Operation(summary = "회원 등록")
    @PostMapping
    public String createUser(@RequestBody UserDto dto) {
        ...
    }
}

 

✅ 5. YAML 명세 (Swagger Editor에서도 사용)

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK

 

✅ 6. 적용 시 주의사항

 

• 운영환경에서 swagger-ui를 차단하거나 접근 제어를 걸어야 함 (API 구조가 노출될 수 있음)
• Spring Security와 함께 사용할 경우 Swagger 경로는 permitAll()로 예외 처리 필요

 

@Override
protected void configure(HttpSecurity http) throws Exception {
    http
        .authorizeRequests()
        .antMatchers("/v3/api-docs/**", "/swagger-ui/**", "/swagger-ui.html").permitAll()
        .anyRequest().authenticated();
}

 

 

✅ OpenAPI 명세(YAML)의 주요 옵션 설명

openapi	OpenAPI 스펙 버전 (예: 3.0.0)
info	API 문서의 메타정보를 포함하는 섹션
info.version	API 버전
info.title	API의 이름
info.description	API 설명
servers	API가 동작할 서버의 URL 목록
servers.url	요청을 보낼 실제 서버 주소
servers.description	해당 서버에 대한 설명
paths	실제 API 경로들을 정의하는 섹션
/{path}	API의 URI (경로) 정의
get, post 등	HTTP 메서드에 대한 정의
summary	API 요청에 대한 간단한 설명
parameters	요청에 사용되는 파라미터 정의 (쿼리, 경로 등)
parameters.name	파라미터 이름
parameters.in	파라미터 위치 (query, path, header, cookie)
parameters.required	필수 여부
parameters.description	파라미터에 대한 설명
parameters.schema.type	데이터 타입 (예: string, integer)
responses	HTTP 응답 정의 (상태코드별 설명)
responses.'200'	HTTP 200 성공 응답
description	응답에 대한 설명
content	응답의 타입과 구조 정의
application/json, text/plain 등	응답 형식 (콘텐츠 타입)
schema	응답 객체의 구조 (필드, 타입 등)
properties	객체 안의 속성 정의

 

 

✅ Swagger UI 직접 구성 (Node.js 기반)

1. GitHub에서 swagger-ui 다운:
   https://github.com/swagger-api/swagger-ui
2. 압축 해제 후 dist/index.html 열기
   • 여기서 url에 OpenAPI 명세 주소 입력
3. 로컬 서버 실행 방법:
4. bash
   npm install -g http-server
   http-server --cors
5. Swagger Editor or SwaggerHub에서 작성한 YAML 명세 파일을 서버에 올려두고,
   index.html에서 그 주소를 url로 입력하면 UI로 확인 가능

---

✅ SwaggerHub 활용 요약

• 주소: https://swagger.io/tools/swaggerhub
• 로그인 후 API 명세 생성
• YAML 또는 JSON 기반으로 작성
• 주소 예시:
  https://app.swaggerhub.com/apis-docs/아이디/API이름/버전
• 실제 테스트 요청도 가능