REST API 실습 & Swagger 문서화 정리

📘 목표

Spring REST API 프로젝트에서 API 명세를 시각화하고,
자동 문서화 + 실시간 테스트를 지원하는 Swagger의 실습 내용을 정리합니다.

---

🌱 Spring REST 관련 Annotation / Class

• @RestController
• @GetMapping, @PostMapping, @PutMapping, @DeleteMapping
• @RequestBody, @PathVariable, @ResponseBody
• ResponseEntity

→ 위 어노테이션들은 Spring REST 기본 구성 요소로, API 엔드포인트를 만들고 응답을 정의하는 데 사용됩니다.

---

📄 API 문서 작성 순서

1. API 명세서 작성 (요청/응답 형식, URI 등)
2. 엔드포인트 정의 (URI, HTTP Method)
3. 요청 파라미터 및 본문 정의
4. 응답 형식 정의 (본문, 헤더, 상태 코드 등)
5. 에러 코드 정의
6. 요청/응답 예제 작성
7. Swagger로 자동 문서화

---

📚 Swagger란?

• REST API를 문서화하고 시각적으로 표현할 수 있도록 해주는 오픈소스 프레임워크
• 실시간 API 테스트 기능까지 지원

---

✅ Swagger의 주요 특징

기능	설명
시각적 표현	Swagger UI로 구조와 작동 방식을 쉽게 파악 가능
실시간 테스트	API를 브라우저에서 직접 테스트 가능
문서 자동화	Java 코드 기반으로 문서 자동 생성 및 갱신 가능

---

🛠 Swagger 사용 방법

1️⃣ 의존성 추가

Spring Boot 2.x (Springfox)

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-boot-starter</artifactId>
  <version>3.0.0</version>
</dependency>

Spring Boot 3.x (springdoc)

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

---

2️⃣ Swagger 설정 (Springdoc 예시)

@Configuration
public class SwaggerConfig {
    
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("My API 문서")
                .version("v1")
                .description("REST API 문서입니다."));
    }
}

---

3️⃣ Swagger 문서 접속 경로

• Springdoc 기본 주소:
  http://localhost:8080/swagger-ui.html
  또는
  http://localhost:8080/swagger-ui/index.html

---

4️⃣ Swagger 문서화 어노테이션

어노테이션	설명
@Operation	각 API 설명 추가
@Parameter	요청 파라미터 설명
@Schema	DTO 필드의 설명 추가
@Tag	API 그룹화
@ApiResponse	응답 설명

예시:

@Operation(summary = "회원 목록 조회", description = "전체 회원 정보를 조회합니다.")
@GetMapping("/users")
public ResponseEntity<List<User>> getUsers() {
    ...
}

---

✅ 요약 정리

• Swagger는 REST API 문서 자동화 도구로 시각적 문서 + 테스트 기능 제공
• API 명세 작성부터 응답 예제, 에러 코드까지 Swagger로 자동화 가능
• Spring Boot 2.x에서는 springfox, 3.x에서는 springdoc을 사용
• 설정 후 http://localhost:8080/swagger-ui 로 접속해 문서 확인 가능
• @Operation, @Parameter, @Schema 등으로 세부 문서 설명도 작성 가능