[web] Swagger에 대해 간단히 알아보자

Minyoung kim·2024년 12월 2일

WEB

목록 보기
5/6

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 응답 상태 코드에 따른 설명을 추가.
  • 응답 코드와 메시지, 반환 데이터의 스키마를 문서화.

속성

속성설명예시
responseCodeHTTP 상태 코드."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 활용법
profile
Minyoung kim
🖐
이전 포스트

[web] CORS에 대한 이해

다음 포스트

[DB] Transaction의 수행과 isolation

0개의 댓글