Swagger

1. Swagger

Swagger는 REST API 문서화 및 테스트 도구입니다. Spring 환경에서 API의 설명, 요청 파라미터, 응답 데이터 구조를 자동으로 문서화해 주고, 브라우저에서 직접 테스트까지 할 수 있습니다.

---

2. Swagger의 기능

• 자동 문서화: Controller의 API를 자동으로 수집해 문서로 변환

• 가독성: API 명세를 표와 예제로 쉽게 확인 가능

• 테스트 편의성: 브라우저에서 API 호출 테스트 가능

• 팀 협업: 프론트엔드·백엔드 간 명확한 API 규약 공유

---

3. Spring Boot에서 Swagger 설정하기

(1) 의존성 추가(spring boot 3.9.4기준)

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.8.9</version>
</dependency>

(2) 실행

의존성 추가 후, 애플리케이션을 실행하면 자동으로 Swagger UI가 활성화됩니다.

• http://localhost:8083/api/swagger-ui/index.html

• http://localhost:8083/api/v3/api-docs

  • JSON형태 API 서버 명세 확인

---

(3) Controller 예시

import org.springframework.web.bind.annotation.*;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;

@RestController
@RequestMapping("/api/users")
@Tag(name = "User API", description = "회원 관리 API")
public class UserController {

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

    @PostMapping
    @Operation(summary = "회원 등록", description = "새로운 회원을 등록합니다.")
    public String createUser(@RequestBody String name) {
        return "Created User: " + name;
    }
}

• @Tag → API 그룹(카테고리)정의

• @Operation → API 설명

---

4. Swagger 주요 어노테이션

어노테이션	설명
@Tag	API 그룹 지정
@Operation	API의 제목·설명 추가
@Parameter	파라미터 설명
@Schema	DTO의 필드 설명
@ApiResponse	응답 코드·메시지 설명