Swagger

---

📘 Swagger란?

정의

Swagger는 Web API를 문서화하고, UI에서 직접 확인하고 테스트할 수 있게 해주는 도구이다. 현재는 OpenAPI와 함께 많이 언급된다.

🎯 사용하는 이유

• API 문서를 자동으로 관리할 수 있다.
• UI에서 직접 요청을 보내며 테스트할 수 있다.
• 개발자 간 API 이해를 쉽게 만든다.
• 요청/응답 구조를 빠르게 확인할 수 있다.

포인트

Swagger는 단순 문서가 아니라 API 문서화와 테스트를 동시에 돕는 도구다.

🧩 주요 개념

• API 정보
• 요청 파라미터
• 응답 스키마
• 상태 코드
• 예제 값
• 인증 설정

🔄 Swagger와 OpenAPI

• Swagger는 원래 API 문서화 생태계의 이름으로 많이 알려져 있다.
• OpenAPI는 현재 표준 스펙에 더 가깝다.
• 실무에서는 Swagger UI, OpenAPI Specification을 함께 이야기하는 경우가 많다.

정리

Swagger라고 부르더라도 실제로는 OpenAPI 기반 문서화를 뜻하는 경우가 많다.

🛠️ Spring Boot 설정 예시

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

🧪 샘플 소스

OpenAPI 설정

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Sample API")
                        .version("v1")
                        .description("Swagger 예시 문서"));
    }
}

Controller 예시

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/users")
public class UserController {

    @Operation(summary = "사용자 조회", description = "ID로 사용자를 조회한다.")
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "조회 성공"),
            @ApiResponse(responseCode = "404", description = "사용자를 찾을 수 없음")
    })
    @GetMapping("/{id}")
    public ResponseEntity<String> findUser(
            @Parameter(description = "사용자 ID", example = "1")
            @PathVariable Long id) {
        return ResponseEntity.ok("user-" + id);
    }
}

🧱 문서에서 자주 보는 요소

• Controller 목록
• HTTP Method
• Request Body
• Query Parameter
• Response Example
• Error Response
• Authentication 정보

🔐 인증과 함께 사용할 때

• JWT 인증 헤더를 넣어 테스트할 수 있다.
• OAuth2와 함께 사용하는 경우 인증 플로우를 문서로 확인하기 좋다.
• 권한별 API 차이를 빠르게 검토할 수 있다.

⚠️ 주의할 점

• 실제 구현과 문서가 다르면 오히려 혼란을 준다.
• 운영 환경에서 공개 범위를 제한하는 것이 좋다.
• 예제 값은 실제 민감 정보가 아니어야 한다.
• 문서 자동 생성만 믿지 말고 설명도 함께 관리해야 한다.

[!important] 정리 Swagger는 API를 문서화하고 테스트하는 실무 도구다. REST API 설계, HTTP Method, 응답 규칙과 함께 관리하면 효과가 크다.

---

연결문서

• REST API 설계
• Restful
• HTTP
• HTTP Method