본문 바로가기
개발지식

스웨거(Swagger)

ydaeng 2025. 1. 10. 21:29
RESTful API를 설계, 문서화, 테스트, 배포하기 위해 사용되는 오픈소스 프레임워크
현재는 OpenAPI Specification(OAS)의 일부로 통합됨
API를 설계할 때 개발자와 클라이언트 간의 커뮤니케이션을 원활히 함
API를 문서 내에서 parameter 조작을 통해 실행할 수 있게 함

"API 문서를 자동으로 만들어 주는 라이브러리"
자동화된 API 문서 생성 / 테스트 환경 제공
어노테이션을 통해 쉽게 적용 가능

 

스웨거 사용의 장점
  • 자동화된 문서화
  • 실시간 테스트
  • 협업 지원

 

Springfox vs Springdoc(OpenAPI 3)

 

두 가지 주요 라이브러리가 있음 !

최근 더 권장되는 것은 Springdoc

≫ Spring Boot와의 통합이 간단하며 유지보수가 더 활발함

 

사용 예시

 

1. 의존성 추가

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.3.0</version>
</dependency>

 

2. YML 설정 추가

springdoc:
  api-docs:
    enabled: true 
    version: openapi_3_0 #사용하는 버전을 명시
    packagesToScan: mokindang.jubging #api-docs 의 스캔 범위를 지정
    path: /v3/api-docs #api 문서 확인 경로, localhost:8080/v3/api-docs 로 접근

  default-consumes-media-type: application/json #기본으로 설정되는 미디어타입 지정
  auto-tag-classes: true #오토 태그 기능 활성화
  groups:
    enabled: false #api 그룹 기능, default는 true 이나 당장 사용하지 않기에 false 로 지정

  swagger-ui:
    operationsSorter: method #method 기준으로 정렬, 그외 alpha 로 정렬 가능
    path: /swagger-ui.html #swagger ui 의 api 문서 확인 경로 defalut 는 /swagger-ui.html 이다.

 

3. Configuration 설정

  • Swagger Config 클래스를 작성해야 함
  • Swagger UI에서 사용될 API 문서를 연결하고, 기본 설정을 관리하는 클래스
package com.alom.dorundorunbe.global.config;

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

@Configuration
public class SwaggerConfig {

  @Bean
  public OpenAPI openAPI() {
    return new OpenAPI()
        .components(new Components())
        .info(apiInfo());
  }

  private Info apiInfo() {
    return new Info()
        .title("[프로젝트 타이틀] API")
        .description("API Description")
        .version("1.0.0");
  }
}

 

4. Controller 구현

  • Swagger에서 렌더링할 실제 API를 작성

 

Controller)

package com.example.api.controller;

import com.example.api.dto.UserCreateRequest;
import com.example.api.dto.UserResponse;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@Tag(name = "사용자 관리", description = "사용자 정보 조회 및 관리 API")
@RestController
@RequestMapping("/api/users")
public class UserController {

    @Operation(summary = "사용자 생성", description = "새로운 사용자를 생성합니다.")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "201", description = "사용자 생성 성공"),
            @ApiResponse(responseCode = "400", description = "잘못된 요청 데이터")
    })
    @PostMapping
    public ResponseEntity<UserResponse> createUser(@RequestBody UserCreateRequest request) {
        UserResponse response = new UserResponse(1L, request.getName(), request.getEmail(), "가입 완료");
        return ResponseEntity.status(HttpStatus.CREATED).body(response);
    }
}
  • @Tag : API 그룹화 - 같은 name으로 묶은 api
  • @Operation : API에 대한 설명 제공 - 어떤 역할인지 명시
  • @ApiResponse : HTTP 응답 코드별 설명 정의

 

Request DTO)

package com.example.api.dto;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Getter;
import lombok.RequiredArgsConstructor;

@Schema(description = "사용자 생성 요청 DTO")
@Getter
@RequiredArgsConstructor
public class UserCreateRequest {

    @Schema(description = "사용자 이름", example = "홍길동")
    private final String name;

    @Schema(description = "사용자 이메일 주소", example = "hong@example.com")
    private final String email;

    @Schema(description = "비밀번호", example = "123456")
    private final String password;
}

 

Response DTO)

package com.example.api.dto;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.AllArgsConstructor;
import lombok.Getter;

@Schema(description = "사용자 응답 DTO")
@Getter
@AllArgsConstructor
public class UserResponse {

    @Schema(description = "사용자 ID", example = "1")
    private final Long id;

    @Schema(description = "사용자 이름", example = "홍길동")
    private final String name;

    @Schema(description = "사용자 이메일 주소", example = "hong@example.com")
    private final String email;

    @Schema(description = "상태 메시지", example = "가입 완료")
    private final String status;
}
  • @Schema : DTO 필드에 대한 상세 설명을 작성 - Swagger 문서에서 필드의 의미를 명확히 함

 

5. 결과 Swagger UI

 

  • Swagger UI 기본 접속 URL : http://localhost:8080/swagger-ui.html
  • 접속하여 api 요청의 응답에 대한 명세 확인 가능

예) 사용자 생성 API

  • URL : POST   /api/users
  • 요청 Body
{
  "name": "홍길동",
  "email": "hong@example.com",
  "password": "123456"
}
  • 응답 Body
{
  "id": 1,
  "name": "홍길동",
  "email": "hong@example.com",
  "status": "가입 완료"
}

 

 

 

 

티스토리툴바