1. Swagger란?

Swagger는 REST API를 설계, 빌드, 문서화, 소비하는 데 유용한 도구입니다. Spring Boot에서는 Springdoc OpenAPI 라이브러리를 사용하여 Swagger UI를 쉽게 설정할 수 있습니다.

2. Gradle 프로젝트에서 Swagger 적용 단계

1단계: 의존성 추가

build.gradle 파일에 다음 의존성을 추가합니다:

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

2단계: Swagger 관련 설정 추가

Springdoc OpenAPI는 기본적으로 /swagger-ui/index.html 경로에서 API 문서를 제공합니다. 일반적인 설정은 추가로 필요하지 않지만, 필요에 따라 설정 파일에 커스터마이징을 할 수 있습니다.

또는 application.properties 파일에 추가:

springdoc.api-docs.path=/api-docs
springdoc.swagger-ui.path=/swagger-ui

3단계: REST API 작성

Swagger는 REST 컨트롤러에서 작성된 API를 자동으로 탐지합니다.

import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/v1")
public class SampleController {

    @GetMapping("/hello")
    public String sayHello() {
        return "Hello, Swagger!";
    }

    @PostMapping("/echo")
    public String echo(@RequestBody String message) {
        return message;
    }
}

4단계: Swagger UI 확인

Spring Boot 애플리케이션을 실행한 후, 브라우저에서 다음 URL에 접속하여 Swagger UI를 확인합니다:

  • Swagger UI: http://localhost:8080/swagger-ui/index.html
  • API Docs (JSON): http://localhost:8080/api-docs

3. 추가 기능 및 고급 설정

1) API 문서 메타데이터 커스터마이징

Swagger 문서에 제목, 설명 등을 추가하려면 아래와 같은 설정을 적용할 수 있습니다.

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

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Sample API")
                        .version("v1.0")
                        .description("This is a sample Spring Boot REST API with Swagger"));
    }
}

5. Swagger UI 주요 화면 구성

  1. API 정보:
    • API 제목, 설명, 버전 등 OAS에 정의된 정보 표시.
  2. 경로 목록:
    • 정의된 API 경로와 메서드(GET, POST 등) 표시.
  3. 요청/응답 구조:
    • 요청 파라미터와 응답 데이터의 구조를 시각적으로 표현.
  4. API 호출 테스트:
    • 입력 값을 설정하고, API를 호출하여 응답 확인.

6. OpenAPI Specification 3.0 주요 요소

6.1 기본 구조

  • openapi: OpenAPI 버전.
  • info: API 메타정보(title, description, version).
  • paths: API 경로와 메서드 정의.
  • components: 재사용 가능한 스키마, 파라미터, 응답 정의.

참고

API Documentation & Design Tools for Teams | Swagger

REST API Documentation Tool | Swagger UI

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

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

Swagger의 주요 어노테이션들

Spring Boot에서 Swagger를 활용하여 REST API를 문서화할 때 사용하는 다양한 어노테이션과 그 목적을 설명합니다. OpenAPI Specification 기반으로 문서를 작성할 때 유용합니다.

1. API 전역 설정 관련 어노테이션

1.1 @OpenAPIDefinition

  • API의 전역적인 메타데이터를 정의하는 어노테이션.
  • 프로젝트 전체에 적용되는 정보(제목, 버전, 서버 정보 등)를 설정.

사용법

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.servers.Server;

@OpenAPIDefinition(
    info = @Info(
        title = "User API",
        version = "1.0",
        description = "사용자 관리를 위한 REST API"
    ),
    servers = @Server(url = "<http://localhost:8080>", description = "Local Server")
)
public class SwaggerConfig {
    // 빈 설정 또는 설정 클래스
}

1.2 @Tag

  • API 그룹(카테고리)을 정의하며, 관련된 엔드포인트를 그룹화.
  • 각 컨트롤러나 메서드에 적용 가능.

사용법

import io.swagger.v3.oas.annotations.tags.Tag;

@Tag(name = "User Management", description = "사용자 관리 관련 API")
@RestController
@RequestMapping("/users")
public class UserController {
    // API 메서드
}

2. 엔드포인트 메서드 관련 어노테이션

2.1 @Operation

  • API 엔드포인트(메서드) 수준에서 문서를 작성.
  • 엔드포인트의 요약, 설명, 응답, 태그 등을 정의.

속성

속성 설명 예시
summary 엔드포인트의 간략한 설명. "사용자 목록 조회"
description 상세 설명. "모든 사용자의 목록을 반환합니다."
tags 엔드포인트가 속한 태그 목록. {"User Management"}
responses 가능한 HTTP 응답 설명. @ApiResponse

사용법

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;

@RestController
public class UserController {

    @Operation(
        summary = "사용자 목록 조회",
        description = "모든 사용자의 목록을 반환합니다.",
        tags = {"User Management"}
    )
    @ApiResponse(responseCode = "200", description = "성공적으로 사용자 목록을 반환")
    @GetMapping("/users")
    public List<String> getUsers() {
        return List.of("홍길동", "이몽룡");
    }
}

2.2 @ApiResponse

  • HTTP 응답 상태 코드에 따른 설명을 추가.
  • 응답 코드와 메시지, 반환 데이터의 스키마를 문서화.

속성

속성 설명 예시

responseCode HTTP 상태 코드. "200"
description 상태 코드 설명. "요청 성공"
content 응답 데이터 타입과 스키마. @Content

사용법

import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;

@ApiResponses({
    @ApiResponse(responseCode = "200", description = "성공적으로 반환"),
    @ApiResponse(responseCode = "404", description = "사용자를 찾을 수 없음")
})
@GetMapping("/users/{id}")
public String getUserById(@PathVariable int id) {
    return "사용자 정보";
}

2.3 @Parameter

  • API 메서드의 파라미터를 문서화.
  • 요청 파라미터의 이름, 설명, 필수 여부 등을 정의.

속성

속성 설명 예시

name 파라미터 이름. "id"
description 파라미터 설명. "사용자 ID"
required 필수 여부. true
example 파라미터의 예제 값. "1"

사용법

import io.swagger.v3.oas.annotations.Parameter;

@GetMapping("/users/{id}")
public String getUserById(
    @Parameter(name = "id", description = "사용자 ID", required = true, example = "1")
    @PathVariable int id
) {
    return "사용자 정보: " + id;
}

3. 요청/응답 데이터 관련 어노테이션

3.1 @Schema

  • 요청/응답 모델의 속성을 정의.
  • 데이터의 타입, 설명, 예제 값을 추가.

사용법

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(description = "사용자 정보 모델")
public class User {
    @Schema(description = "사용자 ID", example = "1")
    private int id;

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

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

    // Getters and Setters
}

3.2 @RequestBody

  • 요청 본문 데이터를 문서화.

사용법

import io.swagger.v3.oas.annotations.parameters.RequestBody;

@PostMapping("/users")
public String createUser(
    @RequestBody(description = "사용자 생성 정보", required = true)
    @io.swagger.v3.oas.annotations.media.Schema(example = "{ \\"name\\": \\"홍길동\\", \\"email\\": \\"hong@example.com\\" }")
    User user
) {
    return "사용자 생성: " + user.getName();
}

3.3 @Content

  • 응답 본문의 데이터 타입과 스키마를 정의.

사용법

import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.responses.ApiResponse;

@ApiResponse(
    responseCode = "200",
    description = "성공적으로 반환",
    content = @Content(mediaType = "application/json", schema = @Schema(implementation = User.class))
)
@GetMapping("/users/{id}")
public User getUserById(@PathVariable int id) {
    return new User(id, "홍길동", "hong@example.com");
}

4. 기타 어노테이션

4.1 @Hidden

  • 특정 엔드포인트나 파라미터를 Swagger UI에서 숨김.

사용법

import io.swagger.v3.oas.annotations.Hidden;

@Hidden
@GetMapping("/admin")
public String adminEndpoint() {
    return "관리자 전용 API";
}

4.2 @SecurityRequirement

  • API의 인증/인가 요구 사항을 정의.

사용법

import io.swagger.v3.oas.annotations.security.SecurityRequirement;

@SecurityRequirement(name = "Bearer Authentication")
@GetMapping("/secure-data")
public String secureData() {
    return "인증된 사용자만 접근 가능";
}

5. 학습 자료

공식 문서

  1. OpenAPI Specification 3.0
  2. Springdoc OpenAPI Documentation

주요 아티클

  1. Swagger와 Spring Boot 통합
  2. Springdoc OpenAPI 활용법

'Spring' 카테고리의 다른 글

Transaction(트랜잭션)과 TCL(Transaction Control Language)  (0) 2025.01.11
MariaDB 엔진 - InnoDB vs MyISAM  (0) 2025.01.10
CORS (Cross-Origin Resource Sharing)  (0) 2025.01.10
AJAX(Asynchronous JavaScript and XML)  (2) 2025.01.10
REST API - @RestController  (0) 2025.01.05

티스토리툴바