백엔드로써 프론트엔드와 협업하기 위해, 커뮤니케이션 비용을 줄인 효율적인 업무를 위해 API 명세서는 반드시 필요하다고 할 수 있다. 명확하게 정리된 API 명세서가 있다면 프론트엔드는 해당 자료를 참고하여 좀 더 수월하게 작업할 수 있고, 서로 엇갈려 불필요한 오류를 맞이할 일도 줄어든다.
1. 의존성 추가
// build.gradle
dependencies {
// 생략..
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.0'
}
build.gradle에 swagger 사용을 위한 springdoc-openapi 의존성을 추가한다.
단 여기서 스프링 부트 버전과 openapi 버전이 반드시 호환되어야 한다.
각 스프링 부트 버전마다 호환되는 범위가 굉장히 좁으니, 아래 링크에서 어떤 버전이 호환되는지 확인한 후 추가하자.
참고로 난 스프링부트 3.4.3 버전이다.
호환되는 버전에 대한 정보는 13.79 (FAQ) 에 존재한다.
OpenAPI 3 Library for spring-boot
Library for OpenAPI 3 with spring boot projects. Is based on swagger-ui, to display the OpenAPI description.Generates automatically the OpenAPI file.
springdoc.org
2. OpenApi 설정 파일 작성
package com.yangsunkue.suncar.config;
import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class OpenApiConfig {
@Bean
public OpenAPI openAPI() {
return new OpenAPI()
// 기본 정보
.info(new Info()
.title("Suncar API")
.version("1.0")
.description("Suncar API 명세서")
.contact(new Contact()
.name("양선규")
.email("ysk9526@gmail.com")))
// JWT 인증 설정 추가
.components(new Components()
.addSecuritySchemes("bearer-jwt", new SecurityScheme()
.type(SecurityScheme.Type.HTTP)
.scheme("bearer")
.bearerFormat("JWT")
.description("JWT 토큰을 헤더에 입력하세요.")));
}
}
OpenApiConfig 설정 파일을 작성한다.
기본 정보와 JWT 인증 설정을 추가한다.
JWT 인증 설정은 반드시 추가해 주어야 한다. 이 설정이 있어야 Swagger 웹에서 JWT 토큰을 포함해 API 테스트를 진행해볼 수 있다.
3. 기타 세부 설정
# application.properties
# 생략 ...
springdoc.swagger-ui.path=/docs
springdoc.api-docs.path=/api-docs
springdoc.swagger-ui.tags-sorter=alpha
springdoc.swagger-ui.operations-sorter=alpha
springdoc.packages-to-scan=com.yangsunkue.suncar.controller
application.properties 파일에 swagger 세부 설정을 작성한다.
각 설정의 의미는 첫째줄 부터 아래와 같다.
1. Swagger 웹 접근 경로 지정 ( 기본값 : swagger-ui.html )
2. json 데이터 접근 경로 지정 ( 기본값 : /v3/api-docs ) -> 이 데이터를 기반으로 Swagger 웹을 구성하게 됨
3. API 태그 정렬 방식 지정 ( 알파벳 순 )
4. 각 태그 내에서 엔드포인트 정렬 방식 지정 ( 알파벳 순 )
5. API 문서화를 위해 스캔할 패키지 지정
이 설정들은 모두 필수 설정값들은 아니다. 단지 편의를 위해 필요한 값들이다.
하지만 맨 마지막 패키지 스캔은 직접 지정해 두는게 좋다. 물론 지정하지 않아도 문서화는 가능하지만, 불필요한 API까지 문서에 포함되는 것을 막기 위해서이다.
4. API 문서 접근 허용 설정 (Spring Security 사용 시)
// SecurityConfig.java
// 생략 ...
@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
http
// CORS 설정
.cors(cors -> cors.configurationSource(corsConfigurationSource()))
.authorizeHttpRequests(requests -> requests
// 인증 없이 접근 가능한 경로 설정
.requestMatchers(
"/auth/**",
"/docs/**",
"/api-docs/**",
"/swagger-ui/**"
).permitAll()
// 그 외 모든 요청은 인증 필요
.anyRequest().authenticated()
)
// CSRF 보호 비활성화 ( RESTAPI에서는 일반적으로 비활성화 )
.csrf(csrf -> csrf.disable())
// 세션 관리 정책을 STATELESS로 설정 (JWT 사용)
.sessionManagement(session -> session
.sessionCreationPolicy(SessionCreationPolicy.STATELESS)
)
// JWT 필터를 UsernamePasswordAuthenticationFilter 앞에 추가
.addFilterBefore(jwtRequestFilter, UsernamePasswordAuthenticationFilter.class);
return http.build();
}
// 생략 ...
Spring Security를 사용하고 있다면, Swagger 관련 경로에 대하여 접근 허용을 해 두어야 한다.
기존 requestMatchers 메서드 안에 아래 3개의 경로를 추가했다.
1. /docs/**
2. /api-docs/**
3. /swagger-ui/**
1번과 2번은 application.properties에서 본인이 설정한 경로를 입력하면 되고, 아예 설정하지 않았다면 각각 / swagger-ui.html/** , /v3/api-docs 로 설정하면 된다.
5. 문서화 할 컨트롤러, 메서드 지정
문서화 하고 싶은 컨트롤러 클래스에 @Tag 어노테이션을 추가한다.
name = "Auth"는 Auth라는 태그에 해당 컨트롤러가 묶이는 것을 뜻한다.
@Tag 어노테이션이 붙은 컨트롤러 하위의 메서드에 @Operation 어노테이션을 붙인다.
summary는 해당 API를 간단히 설명하는 것이며, Swagger 웹에 표시된다.
JWT 토큰이 필요한 태그나 API가 있다면 @SecurityRequirement 어노테이션을 달면 된다.
name은 OpenApiConfig에서 설정했던 이름을 입력한다.
컨트롤러 전체에 달고 싶다면 컨트롤러 클래스 위에, 특정 API에만 달고 싶다면 해당 메서드에만 달면 된다.
6. Swagger 접속 확인
이제 서버를 실행하고 /docs 경로로 접근하면 이렇게 API 명세서를 확인할 수 있다.
표기되는 URL은 /docs가 아닌 걸 확인할 수 있는데, /docs로 접근하면 자동으로 리다이렉션 되는 것 같다.
/users/me API를 보면 우측에 자물쇠 모양이 있다. @SecurityRequirement 태그를 달아둔 API이며, 이 API를 테스트하기 위해서는 토큰이 필요하다는 뜻이다.
Authorize 버튼을 눌러 토큰을 등록해 해당 API를 테스트 해볼 수 있다.
이건 /api-docs로 접속한 화면이다.
데이터가 JSON형태로 출력되는데, 이 데이터를 기반으로 Swagger 웹 화면이 구성되는 것이다.
이렇게 Swagger를 활용한 API 명세서 도입이 완료되었다.
지금은 최대한 간단하게 작성해 본 것이고, 파라미터에 대한 설명이나 리턴되는 상태코드는 어떤 의미인가 등등 다양하고 세부적으로 작성할 수도 있다.
하지만, 기본적으로는 이렇게 간단하게 작성하되 설명이 꼭 필요한 API에 한해서 상세하게 작성하는 게 효율적이라고 할 수 있겠다.
=============
'Development > 썬카(SunCar) - 개인 프로젝트' 카테고리의 다른 글
| [썬카/정기 회고] 스프린트 2 종료 - N+1 문제 (2) | 2025.03.25 |
|---|---|
| [썬카/백엔드] 차량 목록 조회 쿼리 작성 과정에서의 N+1 문제 발생과 해결 (0) | 2025.03.25 |
| [썬카/백엔드] dotenv를 사용한 중요 데이터 환경변수화 (0) | 2025.03.22 |
| [썬카/정기 회고] 스프린트 1 종료 (1) | 2025.03.21 |
| [썬카/백엔드] Spring Security를 이용한 JWT Access Token 발급 및 검증 로직 작성 (0) | 2025.03.11 |