[스프링] Swagger세팅과 사용

스웨거는 현대 웹 서비스에서 자주 사용되는 REST API의 통신 규약을 문서화한 도구이다.

프론트엔드와 백엔드는 이 문서를 기준으로 API 요청과 응답의 구조를 명확하게 공유할 수 있으며,
프론트엔드는 스웨거 문서만 확인해도

“어떤 상황에서 어떤 값을 보내야 하는지, 어떤 데이터를 응답받게 되는지”를 별도로 소통하지 않아도 파악할 수 있다.

 

따라서 이 글에서는 스웨거의 기본 개념과 설정 방법, 그리고 실제 사용하는 방식을 간단하게 정리해본다.

 

1. Swagger가 무엇일까

Swagger(OpenAPI)는 REST API의 구조를 자동으로 분석하여 웹 UI 형태의 문서를 제공하는 도구다.
별도의 수작업 없이 API를 시각적으로 정리해주기 때문에,
프론트·백엔드 협업 효율을 높이고 API 관리의 일관성을 유지할 수 있다.

대표 기능은 다음과 같다:

• API 이름, 설명, URL 정리
• HTTP Method(GET/POST/PUT/DELETE) 표시
• Request Body, Query Parameter 구조 표시
• 응답 예시 및 응답 코드 표시
• 브라우저에서 바로 API 호출 테스트 가능

2. Swagger 세팅

스프링 부트에서 Swagger를 사용하기 위해 다음 의존성을 추가한다.

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

이후 기본 문서 정보와 테스트용 그룹을 설정한다.

// 공통 문서 정보 설정
@Bean
public OpenAPI openAPI() {
    return new OpenAPI()
            .info(new Info()
                    .title("SchoolHubU API")
                    .version("v1")
                    .description("SchoolHubU 개발용 Swagger API 문서"));
}

// 테스트 API 그룹 설정
@Bean
public GroupedOpenApi swaggerTestApi() {
    return GroupedOpenApi.builder()
            .group("Swagger-Test")
            .packagesToScan("com.shu.backend.global.swagger")
            .build();
}

 

Swagger UI 접근 주소는 아래와 같다.

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

이 설정을 적용하면 해당 패키지에 포함된 모든 컨트롤러가
Swagger-Test 그룹 아래에 자동으로 표시된다.

 

http://localhost:8080/swagger-ui/index.html 를 접속하면 다음과 같을 것이다.

세팅은 정확하게 된것을 확인할 수 있다. 이제 간단한 테스트 예시를 통해서 알아보자

 

3. 간단한 테스트 예시

Swagger 동작 방식을 확인하기 위해 DTO와 컨트롤러를 작성한다.

//DTO
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class SwaggerTestDTO {
    private String name;
    private String description;
}

//Controller
@RestController
@RequestMapping("/test/swagger")
public class SwaggerController {

    @GetMapping
    public String swaggerTest() {
        return "Swagger Test";
    }

    @PostMapping
    public String swaggerTestPost(@RequestBody SwaggerTestDTO dto) {
        System.out.println("Name = " + dto.getName());
        System.out.println("Description = " + dto.getDescription());
        return "OK";
    }
}

GET 요청은 단순 확인용 문자열을 반환하고,

POST 요청은 클라이언트가 전달한 name, description 값을 서버에서 확인한 후 "OK"를 반환하도록 구성했다.

 

이제 해당 url에 대해 접근하면 다음과 같이 나온다.

사용자에게 입력 받아야할 스키마까지 볼 수 있다.

 

GET/test/swagger

이를 열어서 Try it out -> Execute를 한다면 다음과 같다.

200 OK와 반환 스트링인 Swagger Test가 정상적으로 출력됨을 볼 수 있다.

 

 

POST/test/swagger

이번엔 사용자에게 이름과 설명을 다음과 같이 입력 받아야한다.

json을 입력하며 실행한다면 다음과 같다.

성공적으로 입력된 것을 확인할 수 있다.

 

결국 이러한 방식으로 프론트엔드는 백엔드가 요구하는 파라미터와 응답 구조를 명확하게 확인할 수 있으며, 별도 커뮤니케이션 없이도 API 사용 방법을 이해할 수 있다. 이를 통해 개발 과정에서 불필요한 오해나 수정 작업을 줄이고 보다 효율적으로 협업할 수 있게 된다.

 

 

4. 실무 방식

위에서 살펴본 기본 설정만으로도 Swagger는 동작한다.
하지만 실제 협업 환경에서는 프론트엔드 담당자가 각 API가 어떤 기능을 수행하는지,

어떤 값을 보내야 하는지,

응답은 어떤 형식인지를 직관적으로 이해할 수 있어야 한다.

 

이를 돕기 위해 Swagger는 다양한 어노테이션을 제공하며,
아래 어노테이션들을 조합하여 문서를 보다 명확하게 작성할 수 있다.

 

@Tag

컨트롤러 단위로 “이 컨트롤러가 어떤 역할을 하는지”를 설정하는 어노테이션이다.
컨트롤러 전체에 대한 이름과 설명을 부여할 수 있다.

@Tag(name = "Swagger",description = "Swagger API")
@RestController
@RequestMapping("/test/swagger")
public class SwaggerController {
	//코드
}

실행 결과:

 

@Operation

특정 API 엔드포인트에 대한 요약(summary)과 상세 설명(description)을 제공한다.
프론트엔드 입장에서는 각 메서드가 어떤 기능을 수행하는지 빠르게 파악할 수 있다.

@Operation(
        summary = "사용자 name과 description 입력",
        description = "사용자 입력이 정확하면 OK를 반환합니다."
)
@PostMapping
public String swaggerTestPost(@RequestBody SwaggerTestDTO dto) {

    System.out.println("Name = " + dto.getName());
    System.out.println("Description = " + dto.getDescription());

    return "OK";
}

실행 결과:

 

@ApiResponses

특정 API가 어떤 상태코드와 설명을 반환할 수 있는지 명시한다.
응답 케이스가 여러 개일 때 특히 유용하며, 실무에서 많이 사용되는 패턴이다.

@ApiResponses({
        @ApiResponse(responseCode = "200", description = "응답 성공"),
        @ApiResponse(responseCode = "400", description = "잘못된 요청")
})
@PostMapping
public String swaggerTestPost(@RequestBody SwaggerTestDTO dto) {

    System.out.println("Name = " + dto.getName());
    System.out.println("Description = " + dto.getDescription());

    return "OK";
}

실행 결과:

위를 확인하면 응답 결과 케이스를 확인할 수 있다.

 

@Content

응답(Response) 또는 요청(Request) Body의 구조를 상세하게 보여주는 설정이다.
특히 Response Body가 어떤 JSON 구조인지 명확히 보여줄 때 사용한다.

@ApiResponses({
        @ApiResponse(
                responseCode = "200",
                description = "응답 성공",
                content = @Content(
                        mediaType = "application/json",
                        schema = @Schema(implementation = SwaggerTestDTO.class)
                )
        ),
        @ApiResponse(responseCode = "400", description = "잘못된 요청")
})
@PostMapping
public String swaggerTestPost(@RequestBody SwaggerTestDTO dto) {
    // 코드
}

실행 결과:

위를 확인하면 200 응답 성공일 경우에 JSON구조로 반한한다는 것을 확인할 수 있다.

 

@Schema

DTO의 각 필드에 대한 설명과 예시(example)를 지정할 수 있다.
Swagger UI에서 Request Body 샘플이 자동으로 채워지기 때문에
프론트엔드가 API를 이해하기 훨씬 쉬워진다.

 

예시 코드:

public class SwaggerTestDTO {
    @Schema(description = "사용자 이름", example = "Ryan")
    private String name;

    @Schema(description = "설명 텍스트", example = "Swagger 테스트 요청입니다.")
    private String description;
}

실행 결과:

 

@Parameter

Query Parameter, Path Variable 등에 대한 설명을 제공할 때 사용한다.
사용자가 입력해야 할 값이 무엇인지 명확하게 안내할 수 있다.

 

@GetMapping("/search")
public String search(
        @Parameter(description = "검색어", example = "apple")
        @RequestParam String keyword,

        @Parameter(description = "페이지 번호", example = "1")
        @RequestParam int page
) {
    return "검색 요청 확인";
}

이와 같이 설정하고 실행한다면

위처럼 비어있는 파라미터가 설정한만큼 적용된다.

 

이와 같이 각 어노테이션을 적절히 활용하면 프론트엔드가 필요한 정보를 명확하게 확인할 수 있고,
API의 기능을 문서만으로 이해할 수 있어 협업 효율이 크게 향상된다.

 

마무리하며:

오늘은 Swagger의 기본 개념부터 설정 방법, 그리고 실무에서 사용하는 주요 어노테이션까지 정리해보았다.

Swagger는 API 구조를 시각적으로 명확하게 보여주기 때문에,
프론트엔드와 백엔드 간의 커뮤니케이션 부담을 줄이고 작업 효율을 높여주는 중요한 도구다.

 

특히 복잡한 API가 많아질수록 문서화의 필요성은 더욱 커지며,
Swagger는 이러한 요구에 맞춰 자동 문서화와 테스트 기능을 동시에 제공한다.

이러한 이유로 Swagger는 현재도 많은 프로젝트에서 핵심적인 개발 도구로 사용되고 있으며,

API 기반 서비스 환경에서 사실상 표준처럼 자리 잡고 있다.

 

 

감사합니다.