1) 왜 “API 명세서”가 필수인가
RESTful API는 “요청을 어떻게 보내면, 어떤 응답이 오는지”가 규칙으로 정리되어 있어야 프론트/다른 서버/외부 개발자가 안전하게 사용할 수 있다. 명세서에는 보통 아래가 들어간다.
- Endpoint 목록 (URL, Method)
- Request 형식 (Path Variable, Query Param, Header, Body JSON)
- Response 형식 (성공/실패, 상태코드, JSON 구조)
- Error 규칙 (예: 400/401/403/404/409/500 등)
- 인증/인가 방식 (JWT, Session, API Key 등)
특히 Spring Data REST를 쓰면 엔드포인트가 자동 생성되기 때문에 “내가 안 만든 것 같지만 실제로 존재하는 API”가 생긴다. 그래서 Swagger(OpenAPI)로 “자동으로 문서화 + 테스트”까지 가능하게 만드는 게 협업/유지보수에 유리하다.
2) Swagger / OpenAPI 개념 정확히 분리
- OpenAPI Specification(OAS): REST API를 문서화하기 위한 “표준 스펙(규격)”
- Swagger UI: 그 표준 스펙(OpenAPI 문서)을 “화면으로 보여주고 테스트”하게 해주는 도구
- springdoc-openapi: Spring Boot에서 OpenAPI 문서를 자동 생성해주는 라이브러리(3.x에서는 jakarta 기반)
3) 프로젝트 설정 (Backend 설정: Spring Boot 계층 관점)
이건 “Backend configuration layer” 작업이다. 컨트롤러/서비스 로직이 아니라, API 문서를 생성하는 설정이다. Spring Boot 3.x는 jakarta 기반이므로 springdoc 2.x 계열을 쓰는 게 핵심.
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.15'- starter 포함: 자동 설정(Auto Configuration)까지 포함되어 충돌/누락 오류가 줄어듦
- webmvc-ui: Swagger UI까지 포함(브라우저에서 확인 가능)
4) application.properties (Spring Data REST basePath 고려)
Spring Data REST는 보통 Repository 기반 엔드포인트가 자동 생성되고, 설정으로 basePath를 /api로 잡는 경우가 많다. 이때 OpenAPI 문서 경로/Swagger UI 경로도 “충돌 없이” 설계해야 한다.
# Swagger UI access path config (default: /swagger-ui/index.html) springdoc.swagger-ui.path=/swagger-ui.html
# OpenAPI doc path springdoc.api-docs.path=/api-docs
# Integrated configuration for Spring Data REST endpoints springdoc.show-data-rest=true
springdoc.show-data-rest=true→ 자동 생성된 Data REST 엔드포인트까지 문서에 포함- Swagger UI 접속은 보통
/swagger-ui/index.html또는 설정한 path 기준으로 접근 - OpenAPI JSON 문서는
/api-docs로 떨어짐(프론트/외부 툴에서도 사용 가능)
5) OpenAPI 문서 메타데이터 커스터마이징 (Bean 등록)
이건 “Backend configuration layer + DI(IoC) 이해”가 같이 들어간다. Swagger UI가 문서를 그릴 때 제목/설명/버전 같은 메타정보를 어디서 가져오냐면, Spring 컨테이너에 등록된 OpenAPI Bean 설정을 참고한다.
package com.korit12.cardatabase.config;
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 OpenApiConfig {
@Bean
public OpenAPI cardatabaseOpenAPI() {
return new OpenAPI()
.info(new Info()
.title("Car Database API")
.description("자동차 및 소유주 관리를 위한 REST API 명세서")
.version("1.0.0")
);
}
}6) @Bean이 왜 중요한가 (IoC/DI 관점에서 한 번에 정리)
- Bean: Spring IoC 컨테이너가 생성하고 생명주기를 관리하는 객체
- @Bean: “이 메서드가 리턴하는 객체를 Bean으로 등록해라”라는 수동 등록 방식
- @Configuration: “여기는 설정 클래스다(Bean 정의 소스다)” 라고 Spring에게 알려줌
즉, Spring이 실행될 때
@Configuration클래스를 스캔해서 “설정 소스”로 인식@Bean메서드를 Spring이 직접 호출해서 객체 생성- 리턴된
OpenAPI객체를 컨테이너가 들고 있다가 - Swagger UI/OpenAPI 문서 생성 시 설정값(제목/설명/버전)으로 사용
7) API의 흐름을 “프론트-백-DB” 연결로 보면
REST API는 결국 “Frontend(HTML/JS/React) → Backend(Spring Boot) → DB(SQL)” 흐름으로 이해해야 한다.
- Frontend: fetch/axios로 HTTP 요청을 보냄 (GET/POST/PUT/PATCH/DELETE)
- Backend Controller: 요청을 받아 DTO로 파싱하고 서비스 호출 (API의 입구)
- Service: 비즈니스 규칙 처리 (도메인 검증/트랜잭션)
- Repository(JPA): DB에 쿼리 실행 및 엔티티 저장/조회
- DB: 테이블 관계(FK), 인덱스, 제약조건으로 데이터 정합성 유지
Swagger(OpenAPI)는 이 중에서 “Frontend가 Controller로 요청을 어떻게 보내야 하는지”를 문서+테스트 화면으로 고정해주는 역할이다.
8) Spring Data REST를 쓸 때 명세서에서 특히 봐야 하는 포인트
- Repository 기반 엔드포인트가 어떤 경로로 노출되는지 (예:
/api/cars,/api/owners) - 응답에 HAL 링크가 포함되는지(
_links,_embedded) - 페이지네이션 파라미터(
page,size,sort)가 자동 제공되는지 - search 리소스(
/api/cars/search)가 어떤 쿼리 메서드를 노출하는지
즉 “내가 컨트롤러에서 만든 API”만 보는 게 아니라, Data REST가 자동 생성한 API까지 Swagger에서 전부 확인해야 한다.
9) 실전 체크리스트
- Swagger UI가 정상 노출되는지
- OpenAPI JSON(
/api-docs)이 내려오는지 - Data REST 엔드포인트까지 문서에 포함되는지
- 각 엔드포인트의 Request/Response 스키마가 의도대로 잡히는지
- 보안(Spring Security)을 붙였을 때 Swagger에서 인증 테스트가 가능한지(추후 단계)
10) 핵심 요약
- OpenAPI는 “명세 표준”, Swagger는 “그 명세를 보여주고 테스트하는 도구”
- Spring Data REST는 자동 생성 API가 많아서 Swagger 문서화 가치가 더 커진다
springdoc-openapi-starter-webmvc-ui를 쓰면 Spring Boot에서 자동 문서화 가능@Bean으로 등록한OpenAPI설정이 Swagger UI의 제목/설명/버전에 반영된다
