[Swagger] Swagger 란? (기본 사용법, 사용 이유)

Swagger란?

• Swagger는 REST API 문서를 자동으로 생성하고 웹 화면에서 직접 API를 테스트할 수 있게 해주는 도구
  • 코드 기반으로 문서 자동 생성
  • 프론트, 백엔드, QA 간 API 명세 공유 표준
  • 요청/응답 구조를 눈으로 확인 + 직접 호출 가능
• Swagger = API 명세서 + 테스트 UI

 

Swagger 사용 이유?

1. 문서 따로 안 써도 됨
   • Controller 코드 + 어노테이션 -> 문서 자동 생성
   • Notion, Excel, Wiki 따로 관리할 필요 감소
2. 프론트와 협업이 쉬움
   • 프론트가 Swagger 보고 바로 API 연동 가능
   • 요청 파라미터, 응답 구조 오해 줄어듦
3. 테스트 도구로 바로 사용
   • Postman 없어도 됨
   • 인증 토큰 넣고 실제 API 호출 가능

 

Swagger의 기반 : OpenAPI

• Swagger는 OpenAPI Specification(OAS) 표준을 따른다
• OpenAPI = API를 정의하는 명세 규격
• Swagger UI = 그 명세를 화면으로 보여주는 도구

 

SpringBoot에서 기본 사용법

• 의존성 추가 (SpringBoot 3.x 기준)

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0'

• 실행 & 접속

http://localhost:8080/swagger-ui.html

 

또는

http://localhost:8080/swagger-ui/index.html

 

-> 호출하면 UI로 API 테스트 가능

 

 

기본 어노테이션 정리

 

• Controller 설명

@Tag(name = "회원 API", description = "회원 관련 기능")
@RestController
@RequestMapping("/api/members")

 

• API 설명

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

 

• 요청/응답 필드 설명

@Schema(description = "회원 이메일", example = "test@test.com")
private String email;

 

• 인증 API 테스트 (JWT)
  • Swagger 상단 Authorize 버튼 사용
  • 이후 모든 API 호출에 Authorization 헤더 자동 포함

 

※ 운영 서버에서는 Swagger 비활성화 권장

내부 정보 노출 방지, 보통 dev나 local 프로파일에서만 사용함

springdoc:
  swagger-ui:
    enabled: false