[Spring] Spring Boot3에 Swagger 적용하기

 

 

 

 

 

개발 환경

 

Spring Boot 3.3.4
JAVA 17
Swagger OpenAPI 3
라이브러리 springdoc-openapi-starter-webmvc-ui:2.6.0

 

 

 

 

 

의존성 추가

 

공식문서에서 버전 확인하기

https://springdoc.org/

OpenAPI 3 Library for spring-boot

 

Gradle

dependencies {

	// swagger
	implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'

}

Maven

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

 

 

 

 

실행 및 확인

 

스웨거 의존성을 추가하게 되면 아래와 같은 URL을 입력하고 들어가면 Local 스웨거(Swagger) UI를 볼 수 있습니다.

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

 

그림1 스웨거 기동 UI

 

 

 

 

스웨거 경로 설정 (선택)

 

스웨거 의존성을 추가하게 되면 아래와 같은 url로 들어가야지만 스웨거(Swagger) UI를 볼 수 있습니다.

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

 

하지만 하나하나 치고 들어가기 너무 귀찮고 외우기도 쉽지 않습니다.

따로 경로 설정을 해두어 편하게 사용하도록 하겠습니다.

 

 

application.yml

springdoc:
  swagger-ui:
    path: {내가하고싶은 경로}

# 설정 예시
springdoc:
  swagger-ui:
    path: /doc

application.properties

springdoc.swagger-ui.path={내가하고싶은 경로}

# 예시
springdoc.swagger-ui.path=/doc

 

 

Tip) localhost:8080/doc 를 입력하고 진입한다해도 URL은 http://localhost:8080/swagger-ui/index.html 로 바뀝니다!

 

 

 

 

주요 어노 테이션 및 클래스 설명

 

@OpenAPIDefinition

• OpenAPI3 스펙에 맞춘 Swagger 설정하는 어노테이션입니다.
• 프로젝트 전체에 대한 기본정보를 제공합니다.

@Info

• @OpenAPIDefinition의 info 속성에서 사용되며, API에 대한 메타데이터(제목, 설명, 버전등)을 정의합니다.

@Server

• 서버 URL과 설명을 설정하는 어노테이션입니다.

GroupedOpenApi

• API들을 그룹으로 나누어 관리할 수 있는 기능 클래스입니다.
• group으로 그룹이름을 설정합니다.
• pathsToMatch로 그룹에 포함할 경로 패턴을 지정합니다.

 

 

 

 

문서화 및 사용법

 

SwaggerConfig 클래스 생성

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;


@OpenAPIDefinition(
    info = @Info(title = "나의 스웨거 제목",
            description = "나의 스웨거 설명",
            version = "v0.0.1"),
    servers = {
            @Server(url = "http://localhost:8080/", description = "로컬 서버"),
            @Server(url = "", description = "테스트 서버"),
    }
)
@Configuration
public class SwaggerConfig {

    @Bean
    public GroupedOpenApi domainSwagger() {
        String[] paths = {"/domain/**"};

        return GroupedOpenApi
                .builder()
                .group("그룹명")
                .pathsToMatch(paths)
                .build();
    }

}

 

Controller 예시

@RestController
@RequiredArgsConstructor
@RequestMapping("/api/boards")
public class BoardController {

    private final BoardService boardService;

    // 게시글 리스트 조회
    @Operation(summary = "게시글 리스트 조회", description = "모든 게시글을 조회합니다.")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "성공", 
                     content = @Content(mediaType = "application/json", 
                     schema = @Schema(implementation = Board.class))),
        @ApiResponse(responseCode = "400", description = "잘못된 요청", 
                     content = @Content),
        @ApiResponse(responseCode = "500", description = "서버 오류", 
                     content = @Content)
    })
    @GetMapping
    public ResponseEntity<List<Board>> getAllBoards() {
        List<Board> boards = boardService.getAllBoards();
        return ResponseEntity.ok(boards);
    }

    // 게시글 상세 조회
    @Operation(summary = "게시글 조회", description = "ID를 통해 특정 게시글을 조회합니다.")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "성공", 
                     content = @Content(mediaType = "application/json", 
                     schema = @Schema(implementation = Board.class))),
        @ApiResponse(responseCode = "404", description = "게시글을 찾을 수 없음", 
                     content = @Content)
    })
    @GetMapping("/{id}")
    public ResponseEntity<Board> getBoardById(
        @Parameter(description = "게시글 ID", required = true) @PathVariable Long id) {
        Board board = boardService.getBoardById(id);
        return ResponseEntity.ok(board);
    }

    // 게시글 생성
    @Operation(summary = "게시글 생성", description = "새로운 게시글을 추가합니다.")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "201", description = "게시글 생성 성공", 
                     content = @Content(mediaType = "application/json", 
                     schema = @Schema(implementation = Board.class))),
        @ApiResponse(responseCode = "400", description = "잘못된 요청", 
                     content = @Content)
    })
    @PostMapping
    public ResponseEntity<Board> createBoard(
        @Parameter(description = "새 게시글의 정보", required = true) @RequestBody Board board) {
        Board createdBoard = boardService.createBoard(board);
        return ResponseEntity.status(201).body(createdBoard);
    }

    // 게시글 수정
    @Operation(summary = "게시글 수정", description = "ID를 통해 특정 게시글을 수정합니다.")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "게시글 수정 성공", 
                     content = @Content(mediaType = "application/json", 
                     schema = @Schema(implementation = Board.class))),
        @ApiResponse(responseCode = "404", description = "게시글을 찾을 수 없음", 
                     content = @Content)
    })
    @PutMapping("/{id}")
    public ResponseEntity<Board> updateBoard(
        @Parameter(description = "게시글 ID", required = true) @PathVariable Long id,
        @Parameter(description = "수정할 게시글의 정보", required = true) @RequestBody Board board) {
        Board updatedBoard = boardService.updateBoard(id, board);
        return ResponseEntity.ok(updatedBoard);
    }

    // 게시글 삭제
    @Operation(summary = "게시글 삭제", description = "ID를 통해 특정 게시글을 삭제합니다.")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "204", description = "게시글 삭제 성공", 
                     content = @Content),
        @ApiResponse(responseCode = "404", description = "게시글을 찾을 수 없음", 
                     content = @Content)
    })
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteBoard(
        @Parameter(description = "게시글 ID", required = true) @PathVariable Long id) {
        boardService.deleteBoard(id);
        return ResponseEntity.noContent().build(); // 204 No Content
    }
}

 

그림2 등록된 API

 

그림3 등록된 API 상세

 

감사합니다.