[Spring] Swagger - API 명세서 작성

Swagger는 Spring-Fox, Spring-Doc 2가지 라이브러리가 존재한다.

Spring-Fox는 오래전에 나온 라이브러리이기 때문에, Spring-Doc를 사용할 예정이다.

 

 

1. 의존성 추가

dependencies {
	
    . . .

	//Security
	implementation 'org.springframework.boot:spring-boot-starter-security'
	testImplementation 'org.springframework.security:spring-security-test'

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

 

 

 

2. SwaggerConfig 작성

import io.swagger.v3.oas.models.servers.Server;
import io.swagger.v3.oas.models.Components;
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("Budget-Management RestAPI")
                .description("예산 관리 어플리케이션 API 문서");

        return new OpenAPI()
                .addServersItem(new Server().url("/").description("HTTPS 설정"))
                .components(new Components())
                .info(info);
    }

}

 

Info 객체에 API의 버전 정보, 문서 제목, 설명을 포함한 Swagger 문서 메타데이터를 정의한다.

OpenAPI를 사용하여 API 문서화 작업을 자동으로 처리하도록 설정한다.

 

 

3. API 명세서 작성

import backend.budget.auth.dto.RegisterRequest;
import backend.budget.auth.service.UserService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.validation.Valid;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Slf4j
@RestController
@RequestMapping("/api")
@Tag(name = "Auth-Controller", description = "Auth API")
public class AuthController {

    private final UserService userService;

    @Autowired
    public AuthController(UserService userService) {
        this.userService = userService;
    }

    @Operation(
            summary = "회원가입 API",
            responses = {
                    @ApiResponse(
                            responseCode = "200",
                            description = "SUCCESS_SIGNUP"
                    ),
                    @ApiResponse(
                            responseCode = "409",
                            description = "USERNAME_ALREADY_EXIST"
                    )
            }
    )
    @PostMapping("/signup")
    public void signup(@RequestBody @Valid RegisterRequest request){
        log.info("[회원가입 요청] ID: {}", request.getUserName());
        userService.register(request);
    }
}

 

API 호출이 성공, 실패했을 때 반환되는 응답을 정의한다.

 

 

4. Security Config 작성

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.web.cors.reactive.UrlBasedCorsConfigurationSource;

import java.util.Arrays;

@EnableWebSecurity
@Configuration
public class SecurityConfig {
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.csrf(csrf -> csrf.disable())
                .cors(cors -> cors.disable()) // CORS 설정
                .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
                .authorizeHttpRequests(authorize -> authorize
                        .requestMatchers("/api/signup", "/api/login").permitAll()
                        .requestMatchers(
                                "/api-docs/**",
                                "/swagger-ui/**"
                        ).permitAll().anyRequest().authenticated());
        return http.build();
    }
}

 

Swagger-UI를 접속하기 위해서는 Security Config에 Swagger 도메인을 허용하는 설정이 필요하다.

 

 

5. application.properties 작성

# swagger-ui (http://localhost:9090/swagger-ui/index.html)
springdoc.swagger-ui.path=/swagger-ui.html

#OpenAPI JSON (http://localhost:9090/api-docs)
springdoc.api-docs.path=/api-docs

 

Swagger의 기본 경로를 지정하면 다음과 같은 도메인으로 접속이 가능하다.

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

 

모든 설정을 마친 후 Swagger-UI 에 접속해본 결과, 다음과 같이 잘 정리된 API 명세서를 볼 수 있었다.