[Spring] Swagger

1. 소개

Swagger란?

 

REST API 문서를 자동으로 생성하고 테스트할 수 있도록 도와주는 도구

Spring Boot에서 API를 만들면 보통 어떤 엔드포인트가 있고, 어떤 요청과 응답이 있는지 문서를 만들어야 하는데, Swagger를 사용하면 이 과정을 자동화할 수 있다.

 

기능

API 문서를 자동으로 생성

• 코드에 어노테이션을 추가하면 문서가 자동으로 생성됨

API를 웹 UI에서 바로 테스트

• Swagger UI를 통해 API를 직접 호출하고 응답을 확인할 수 있음

API 명세를 JSON/YAML 형식으로 제공해서 다른 개발자나 클라이언트가 쉽게 연동

• OpenAPI Specification(OAS) 기반으로 API를 표준화할 수 있음

코드와 동기화된 문서 유지

• 코드 변경 시 API 문서도 자동으로 업데이트 

 

2. Swagger 설정

1) 의존성 추가 - build.gradle

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

 

2) Swagger 활성화 (application.yml)

springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    path: /swagger-ui.html

 

 

3) Swagger 설정 파일 작성 (SwaggerConfig.java)

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

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("My API")
                        .version("1.0")
                        .description("Swagger를 이용한 Spring Boot API 문서입니다."));
    }
}

 

 

4) Swagger 문서 확인

Spring Boot 애플리케이션 실행 후 웹 브라우저에서 Swagger UI 확인 가능

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

 

API 명세 JSON 확인

http://localhost:8080/v3/api-docs

 

3. Swagger 사용 예제

 

Controller에 API 문서 적용

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

@RestController
@RequestMapping("/api/users")
@Tag(name = "User API", description = "유저 관련 API")
public class UserController {

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

    @Operation(summary = "유저 생성", description = "새로운 유저를 생성합니다.")
    @PostMapping
    public String createUser(@RequestBody String name) {
        return "Created User: " + name;
    }
}

 

 

 

 

4. 정리

API 문서를 자동으로 관리할 수 있다

 

백엔드와 프론트엔드 협업이 쉬워짐

 

웹 UI에서 바로 API를 테스트할 수 있다

 

API 명세를 JSON/YAML로 제공하여 연동이 쉬움