Spring Boot에서 API 문서를 작성하는 쉬운 방법: Swagger

Spring Boot에서 API 문서를 작성하는 쉬운 방법: Swagger

Spring Boot 애플리케이션에서 API 문서를 자동으로 생성하고 관리하기 위해 Swagger를 활용할 수 있습니다. Swagger는 RESTful API를 시각화하고, 테스트하며, 문서화하는 데 매우 유용한 도구입니다. 이 글에서는 Swagger를 Spring Boot에 통합하고 사용하는 방법을 단계별로 설명합니다.

---

1. Swagger란?

Swagger는 RESTful API를 설계하고 문서화하기 위한 오픈 소스 도구입니다. Swagger UI를 사용하면 API의 엔드포인트와 요청/응답 구조를 웹 페이지에서 쉽게 확인할 수 있습니다.

---

2. 프로젝트에 Swagger 추가하기

1. 의존성 추가

Maven 프로젝트에서는 springdoc-openapi-ui를 추가합니다:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version>
</dependency>

Gradle 프로젝트에서는 다음을 추가합니다:

dependencies {
    implementation 'org.springdoc:springdoc-openapi-ui:1.7.0'
}

2. 애플리케이션 실행

Spring Boot 애플리케이션을 실행하면 Swagger UI가 기본적으로 /swagger-ui.html 경로에서 제공됩니다.

---

3. Swagger 설정

Spring Boot 애플리케이션에서 추가적인 설정을 적용하려면 application.yml 또는 application.properties 파일을 수정할 수 있습니다.

application.yml 예제:

springdoc:
  api-docs:
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html

설명:

• /v3/api-docs: API 문서를 JSON 형식으로 반환합니다.
• /swagger-ui.html: Swagger UI 웹 인터페이스 경로를 설정합니다.

---

4. 간단한 컨트롤러 작성

Swagger는 컨트롤러와 메서드에 작성된 어노테이션을 기반으로 API 문서를 생성합니다.

컨트롤러 예제:

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

@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping
    public String getAllUsers() {
        return "모든 사용자 목록을 반환합니다.";
    }

    @PostMapping
    public String createUser(@RequestBody String user) {
        return "사용자가 생성되었습니다: " + user;
    }

    @GetMapping("/{id}")
    public String getUserById(@PathVariable Long id) {
        return "사용자 ID: " + id;
    }
}

Swagger는 위의 코드에서 각 엔드포인트에 대한 정보를 자동으로 문서화합니다.

---

5. Swagger UI 확인

애플리케이션을 실행한 후 브라우저에서 http://localhost:8080/swagger-ui.html에 접속하면 Swagger UI가 나타납니다. 여기에서 다음 작업을 수행할 수 있습니다:

• API 엔드포인트 확인:
  Swagger UI는 컨트롤러별로 API 엔드포인트를 정리해 보여줍니다.

• 요청 테스트:
  각 엔드포인트에 대해 직접 요청을 보내고 응답을 확인할 수 있습니다.

---

6. OpenAPI 어노테이션 추가 (선택 사항)

OpenAPI 어노테이션을 활용하면 API 문서를 더욱 상세히 작성할 수 있습니다.

예제:

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.parameters.RequestBody;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/products")
public class ProductController {

    @Operation(summary = "모든 제품 조회", description = "모든 제품의 리스트를 반환합니다.")
    @GetMapping
    public String getAllProducts() {
        return "모든 제품 목록";
    }

    @Operation(summary = "새로운 제품 추가", description = "새로운 제품을 추가합니다.")
    @PostMapping
    public String addProduct(@RequestBody String product) {
        return "제품이 추가되었습니다: " + product;
    }
}

결과:
Swagger UI에 각 API의 설명과 요청/응답 정보가 추가됩니다.

---