Swagger를 사용한 API 문서화

 

API는 현대 애플리케이션 개발에서 필수적인 요소이며, 이를 효율적으로 관리하고 사용자에게 전달하려면 명확하고 직관적인 문서화가 필요합니다. Swagger는 API를 문서화하고 테스트하며 관리할 수 있도록 도와주는 대표적인 도구로, 스프링 부트 3와도 훌륭하게 통합됩니다. 이 글에서는 Swagger를 사용하여 API 문서를 작성하는 방법과 구체적인 예시 3가지를 살펴보겠습니다.

---

1. Swagger란 무엇인가?

Swagger는 API의 정의와 문서를 작성하기 위한 오픈 소스 프레임워크입니다. 최근에는 OpenAPI로 이름이 변경되었으며, 다양한 언어와 플랫폼에서 사용할 수 있습니다. Swagger는 다음과 같은 주요 이점을 제공합니다.

• 자동화된 문서 생성: 코드에 주석만 작성하면 API 문서가 자동으로 생성됩니다.
• 시각화된 인터페이스 제공: Swagger UI를 통해 API를 쉽게 탐색하고 테스트할 수 있습니다.
• 표준화된 API 정의: OpenAPI Specification(OAS)을 기반으로 API를 명확히 정의합니다.

---

2. 스프링 부트 3에서 Swagger 설정하기

스프링 부트 3에서 Swagger를 사용하려면 springdoc-openapi 라이브러리를 활용합니다. 이 라이브러리를 사용하면 최소한의 설정으로 OpenAPI 문서와 Swagger UI를 구현할 수 있습니다.

(1) Maven 의존성 추가

다음 의존성을 pom.xml에 추가합니다.

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version>
</dependency>

(2) 기본 설정

라이브러리를 추가하면 기본적으로 /swagger-ui.html 경로에서 Swagger UI에 접근할 수 있습니다. 별도의 설정이 필요 없는 점이 장점입니다.

(3) OpenAPI 문서 커스터마이징

application.yml 또는 application.properties에서 OpenAPI 정보를 설정할 수 있습니다.

application.yml 예시:

springdoc:
  api-docs:
    path: /api-docs
  swagger-ui:
    path: /swagger-ui.html
  info:
    title: API 문서 예제
    version: 1.0.0
    description: API 문서화 예제 프로젝트입니다.

---

3. 실제 예제

예제 1: 기본 컨트롤러 API 문서화

아래는 간단한 REST API를 Swagger로 문서화한 예제입니다.

코드 예제:

@RestController
@RequestMapping("/api")
public class ExampleController {

    @Operation(summary = "Hello API", description = "Hello 메시지를 반환합니다.")
    @GetMapping("/hello")
    public ResponseEntity<String> sayHello() {
        return ResponseEntity.ok("Hello, Swagger!");
    }
}

결과:
Swagger UI에서 /api/hello 경로와 관련된 API 설명 및 테스트 옵션이 자동 생성됩니다.

---

예제 2: DTO와 함께 사용하기

DTO를 사용하는 경우, Swagger는 요청 및 응답 데이터를 명확히 정의합니다.

코드 예제:

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

    @Operation(summary = "사용자 등록", description = "새로운 사용자를 등록합니다.")
    @PostMapping
    public ResponseEntity<UserResponse> createUser(@RequestBody UserRequest userRequest) {
        UserResponse response = new UserResponse(1L, userRequest.getName(), "Success");
        return ResponseEntity.ok(response);
    }
}

@Data
class UserRequest {
    private String name;
    private String email;
}

@Data
@AllArgsConstructor
class UserResponse {
    private Long id;
    private String name;
    private String status;
}

Swagger UI 결과:

• POST /api/users 요청에 필요한 JSON 형식이 자동으로 표시됩니다.
• 응답 예시 또한 자동 생성됩니다.

---

예제 3: JWT 인증과 함께 사용하기

보안이 필요한 API의 경우 JWT 토큰을 Swagger에 추가할 수 있습니다.

코드 예제:

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .addSecurityItem(new SecurityRequirement().addList("BearerAuth"))
            .components(new Components().addSecuritySchemes("BearerAuth",
                new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT")));
    }
}

@RestController
@RequestMapping("/api/protected")
public class ProtectedController {

    @Operation(summary = "보호된 API", description = "JWT 토큰이 필요합니다.")
    @SecurityRequirement(name = "BearerAuth")
    @GetMapping
    public ResponseEntity<String> getProtectedData() {
        return ResponseEntity.ok("이 데이터는 보호되고 있습니다.");
    }
}

Swagger UI 결과:

• JWT 토큰 입력란이 자동으로 생성됩니다.
• 보호된 API를 테스트할 수 있습니다.

---

4. 마무리

Swagger는 스프링 부트 3 프로젝트에서 API 문서를 효율적으로 작성하고 관리하는 데 큰 도움이 됩니다. 위에서 다룬 기본 설정, DTO 활용, 그리고 JWT 인증 적용 예제를 통해 Swagger의 강력한 기능을 활용해 보세요.

Swagger를 잘 활용하면 개발팀 간의 협업이 쉬워지고, 외부 사용자와의 커뮤니케이션도 명확해집니다. 이제 스프링 부트 프로젝트에서 Swagger를 도입하여 API 문서화를 시작해 보세요!