Spring Boot3 스웨거(Swagger) 설정 및 사용 방법

fever·2024년 5월 30일

Spring Boot + React 공부

목록 보기

2/7

스웨거(Swagger)란?
API 문서를 자동으로 생성해주는 도구로, 이를 통해 RESTful API의 구조와 동작 정의 가능

0. 개발환경

스프링부트 3.3.0
자바 17

1. build.gradle 의존성 추가

// Swagger
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.4'

SpringDoc OpenAPI?
OpenAPI 3.0 사양을 지원하는 라이브러리로 REST 엔드포인트를 자동으로 문서화함 (3이전에는 SpringFox를 사용했으나 3부터는 지원을 안해서, SpringDoc로 바꿔서 진행)

2. SwaggerConfig 설정

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

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI openAPI() {
        Info info = new Info()
                .version("v1.0") //버전
                .title("CineBite API") //이름
                .description("영화 커뮤니티 프로젝트 API"); //설명
        return new OpenAPI()
                .info(info);
    }

}

3. Swagger UI 추가 설정 (선택사항)

application.properties나 xml에 설정 가능

#swagger-ui 설정
#swagger-ui 접속 경로(http://localhost:4000/swagger-ui/index.html)
springdoc.swagger-ui.path=/swagger-ui.html

#OpenAPI JSON 문서 확인 주소 (http://localhost:4000/api-docs)
springdoc.api-docs.path=/api-docs

#기본 요청 컨텐츠 json
springdoc.default-consumes-media-type=application/json
springdoc.default-produces-media-type=application/json

#ui 알파벳 순 정렬
springdoc.swagger-ui.operations-sorter=alpha
springdoc.swagger-ui.tags-sorter=alpha

#swagger url 비활성화, json화 된 config 파일 대신 파라미터를 이용하여 swagger-ui에 접근하도록 함
springdoc.swagger-ui.disable-swagger-default-url=true
springdoc.swagger-ui.display-query-params-without-oauth2=true
springdoc.swagger-ui.doc-expansion=none

4. TestControllerDocs

어노테이션을 컨트롤러에 달아서 직접적으로 사용이 가능하나, 길어서 보기도 싫고 가독성이 구려지기 때문에 인터페이스로 사용하는 것을 추천

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestBody;

import io.swagger.v3.oas.annotations.Operation;
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 java.util.List;

@Tag(name = "Test", description = "Test 관련 API입니다.")
public interface TestControllerDocs {

    @Operation(summary = "유저 정보 저장", description = "유저 정보를 저장합니다.")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "유저 정보 저장 성공"),
            @ApiResponse(responseCode = "409", description = "유저 정보 저장 실패(유저 중복)") })
    public ResponseEntity<String> testPost(@RequestBody TestEntity userInfo);

    @Operation(summary = "전체 유저 정보 반환", description = "전체 유저 정보를 반환합니다.")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "유저 전체 정보 반환 성공"),
            @ApiResponse(responseCode = "400", description = "유저 전체 정보 반환 실패") })
    public ResponseEntity<List<TestEntity>> testGet();

}

5. TestController

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

import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;

import java.util.List;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;

@Slf4j
@RestController
@RequiredArgsConstructor
@RequestMapping("/test")
public class TestController implements TestControllerDocs {

    private final TestService testService;

    @PostMapping("/save")
    public ResponseEntity<String> testPost(@RequestBody TestEntity userInfo) {
        log.info("유저 정보 저장 컨트롤러 실행");
        try {
            testService.save(userInfo);
            return ResponseEntity.ok("유저 정보 저장 완료");
        } catch (Exception e) {
            e.printStackTrace();
            return ResponseEntity.status(400).body("유저 정보 저장 실패");
        }
    }

    @GetMapping("/findAll")
    public ResponseEntity<List<TestEntity>> testGet() {
        log.info("유저 정보 반환 컨트롤러 실행");

        try {
            List<TestEntity> testEntity = testService.findAll();
            return ResponseEntity.ok(testEntity);
        } catch (Exception e) {
            e.printStackTrace();
            return ResponseEntity.status(400).body(null);
        }
    }

}