스프링 3.x에서 Swagger 적용하기

스프링 3.x 프로젝트에서 API 문서화를 위한 강력한 도구인 Swagger를 적용하고 싶으신가요? 본 가이드에서는 springdoc-openapi-starter-webmvc-ui 라이브러리를 이용하여 스프링 3.x 프로젝트에 Swagger를 쉽고 빠르게 통합하는 방법을 자세히 알려드립니다.

Swagger는 RESTful API를 개발하고 문서화하는 데 있어 필수적인 도구입니다. 개발 중에 API 구조를 시각적으로 확인하고, 다른 개발자들과 쉽게 API를 공유할 수 있도록 도와줍니다. 특히, 스프링 부트 프로젝트에서는 Springfox Swagger가 많이 사용되었지만, 스프링 3.x부터는 Springfox 대신 Springdoc이 공식적으로 지원되고 있습니다.

Springdoc이란?

Springdoc은 Spring Boot 프로젝트에서 Swagger UI를 쉽게 사용할 수 있도록 지원하는 라이브러리입니다. Springdoc은 Spring Boot의 자동 설정 기능을 활용하여 최소한의 설정으로 Swagger UI를 사용할 수 있도록 해줍니다.

springdoc-openapi-starter-webmvc-ui 라이브러리 소개

springdoc-openapi-starter-webmvc-ui는 Springdoc에서 제공하는 스타터 프로젝트입니다. 이 스타터를 사용하면 Swagger UI를 위한 모든 의존성을 자동으로 관리할 수 있습니다.

개발 환경 설정

• Java: 11 이상
• Spring Boot: 3.x
• 빌드 도구: Maven
• IDE: IntelliJ IDEA, Eclipse 등

728x90

Maven 프로젝트 설정

1. pom.xml에 의존성 추가:
    

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

    

    
2. 프로젝트 빌드 및 실행:
3. Maven 명령어를 사용하여 프로젝트를 빌드하고 실행합니다.

 

2024.11.16 - [SpringBoot 를 배워보자] - Swagger-UI, 개발 환경에서만 노출하고 운영 환경에서는 숨기는 방법: 상세 가이드

 

Swagger 설정

• 기본 설정:
• springdoc-openapi-starter-webmvc-ui를 추가하면 기본적인 Swagger 설정이 자동으로 적용됩니다. 프로젝트를 실행하고 http://localhost:8080/swagger-ui/index.html로 접속하면 Swagger UI를 확인할 수 있습니다.
• 커스터마이징:

  @RestController
  @RequestMapping("/api")
  public class MyController {
  
      @GetMapping("/hello")
      @Operation(summary = "Hello World API", description = "Hello 메시지를 반환합니다.")
      public String hello() {
          return "Hello World";
      }
  }
  

• Swagger UI를 커스터마이징하려면 @Operation, @Tag, @ApiResponse 등의 어노테이션을 사용하여 API에 대한 상세한 정보를 추가할 수 있습니다.

주요 어노테이션 및 활용 예시

• @Operation: API에 대한 전반적인 설명을 제공합니다.
• @Tag: API를 태그로 분류하여 관리합니다.
• @ApiResponse: API의 다양한 응답 상태 코드와 예시를 정의합니다.

 

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
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.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/users")
@Tag(name = "User Management", description = "유저 관리 API")
public class UserController {

    @GetMapping("/{userId}")
    @Operation(summary = "유저 정보 조회", description = "특정 유저의 정보를 조회합니다.")
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "유저 정보 조회 성공", 
                         content = @Content(schema = @Schema(implementation = User.class))),
            @ApiResponse(responseCode = "404", description = "유저를 찾을 수 없습니다.")
    })
    public User getUser(@PathVariable Long userId) {
        // ...
    }
}

 

 

위 코드에서 사용된 어노테이션의 의미:

• @Tag: 해당 컨트롤러의 모든 API를 "User Management" 태그로 분류합니다.
• @Operation: getUser 메소드에 대한 간략한 설명과 상세한 설명을 제공합니다.
• @ApiResponses: 다양한 응답 상태 코드에 대한 설명과 예시를 정의합니다.
  • @ApiResponse(responseCode = "200", description = "유저 정보 조회 성공", content = @Content(schema = @Schema(implementation = User.class))): 200 상태 코드일 때 User 객체를 반환하며, User 클래스에 대한 스키마 정보를 제공합니다.
  • @ApiResponse(responseCode = "404", description = "유저를 찾을 수 없습니다."): 404 상태 코드일 때 발생하는 오류 메시지를 설명합니다.

추가적인 커스터마이징

• @Parameter: API 파라미터에 대한 설명을 추가합니다.
• @RequestBody: 요청 body에 대한 스키마를 정의합니다.
• @RequestBody: 응답 body에 대한 스키마를 정의합니다.
• @ApiImplicitParam: 추가적인 파라미터 정보를 제공합니다.
• @ApiImplicitParams: 여러 개의 @ApiImplicitParam을 한꺼번에 사용할 때 사용합니다.

Swagger UI 설정

• Swagger Configuration: Spring Boot 설정 파일에서 Swagger 설정을 추가하여 Swagger UI를 사용할 수 있도록 합니다.
• Docket Bean: Docket Bean을 생성하여 Swagger UI에 노출될 API를 설정합니다.
• Customizer: Swagger UI의 외형이나 기능을 커스터마이징하기 위해 Customizer를 사용할 수 있습니다.

 

Swagger UI 사용하기

• API 목록: Swagger UI에서 API 목록을 확인하고 각 API에 대한 상세 정보를 볼 수 있습니다.
• 요청 및 응답: API를 직접 호출하여 요청과 응답을 확인하고 테스트할 수 있습니다.
• 모델 구조: API에서 사용되는 모델의 구조를 확인할 수 있습니다.

추가 기능

• 보안 설정: Basic Authentication, OAuth2 등 다양한 보안 설정을 지원합니다.
• 커스터마이징: Swagger UI의 외형과 기능을 커스터마이징할 수 있습니다.
• 플러그인: 다양한 플러그인을 사용하여 Swagger UI를 확장할 수 있습니다.

728x90

본 가이드에서는 스프링 3.x 프로젝트에 Swagger를 적용하는 방법을 상세히 설명했습니다. springdoc-openapi-starter-webmvc-ui를 사용하면 간단한 설정만으로 Swagger UI를 사용할 수 있으며, 다양한 커스터마이징 기능을 통해 API 문서를 더욱 풍부하게 만들 수 있습니다.

참고 자료

• Springdoc 공식 문서: https://springdoc.org/
• Spring Boot 문서: https://spring.io/guides/gs/spring-boot/