🔙뒤로가기

Spring Boot 프로젝트에서 Swagger를 사용하려면 먼저 의존성을 추가해야 한다. 여기서는 Springdoc OpenAPI 라이브러리를 사용한다.

1. build.gradle에 의존성 추가

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

<aside> 💡 이 버전은 예시이며, 가장 최신의 버전을 사용하는 것을 권장한다. 항상 라이브러리의 공식 문서를 참고하여 최신 버전을 확인하고 사용하도록 하자.

</aside>

2. application.yml에 설정 추가

기본적으로는 별도의 설정 없이도 동작하지만, 필요에 따라 다음과 같은 설정을 추가할 수 있다.

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

이 설정들은 각각 Swagger UI 활성화 여부 및 경로, API 문서의 경로를 설정한다.

3. SwaggerConfig.class 작성

package com.MongMoong.MongBitProject.config;

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .components(new Components()
                        .addSecuritySchemes("JWT",
                                new SecurityScheme()
                                        .type(SecurityScheme.Type.HTTP)
                                        .scheme("bearer")
                                        .bearerFormat("JWT")
                                        .in(SecurityScheme.In.HEADER)
                                        .name("Authorization")))
                .info(new Info()
                        .title("MongBit API DOC")
                        .version("1.0")
                        .description("몽빗 API 명세서")
                        .termsOfService("<http://swagger.io/terms/>")
                        .license(new License().name("Apache 2.0").url("<http://springdoc.org>")));
    }
}

4. API 문서화

Swagger는 주로 컨트롤러에 작성된 애노테이션을 바탕으로 API 문서를 생성한다. 따라서 각 API 엔드포인트에 알맞은 애노테이션을 추가하고, API에 대한 설명, 예상되는 요청과 응답 등을 작성하면 된다.

@RestController
@RequiredArgsConstructor
@RequestMapping("/api/v1/test")
@Tag(name = "Comment Controller", description = "댓글과 관련된 API를 제공하는 컨트롤러입니다.")
public class CommentController {

    private final CommentService commentService;

    @PostMapping("/comments")
    @Operation(
            summary = "특정 테스트에 대한 새로운 댓글 생성",
            description = "Request body의 값을 memberId, testId, content 순서로 전달해주세요.")
    @SecurityRequirements(value = {@SecurityRequirement(name = "JWT")})
    public ResponseEntity<Comment> createComment(@RequestBody Comment comment) {
        Comment savedComment = commentService.saveComment(comment);
        return ResponseEntity.status(HttpStatus.CREATED).body(savedComment);
    }

5. API 문서 확인

위의 설정이 완료되면, Swagger UI를 통해 생성된 API 문서를 확인할 수 있다. 브라우저에서 {host}:{port}/swagger-ui.html (예: http://localhost:8080/swagger-ui.html) 로 접속하면, Swagger UI가 보이며 이를 통해 API 문서를 탐색하고, 실제 요청을 보내고 응답을 확인할 수 있다.

<aside> 💡 API 명세서는 애플리케이션이 빌드되며 만들어진다. 코드 수정 시 즉시 반영되는 것이 아니다. 또한 클라우드 환경일 경우 명세서를 렌더링하는 데에 메모리 소모가 상당하므로 512MB 이상의 메모리를 확보하는 것이 좋다.

</aside>