스프링 공부에서 진짜 실력은 "막혔을 때 공식 문서를 찾아 읽는 능력"에서 갈려요. 스프링 문서는 두 종류(레퍼런스 · Javadoc)인데, 이 둘을 언제·어떻게 보는지만 알면 검색보다 훨씬 빠르고 정확해집니다. 도식과 함께 차근차근 봐요.
🎯 이 부록을 끝내면
스프링 문서가 레퍼런스(Reference)와 Javadoc(API) 두 종류라는 걸 구분할 수 있어요.
"지금 궁금한 게 무엇이냐"에 따라 어느 문서를 열지 스스로 판단할 수 있어요.
Spring Framework·Boot·Data·Security가 각각 별도 문서를 가진다는 지도를 그릴 수 있어요.
레퍼런스/Javadoc 화면의 각 부분이 무엇인지 알고, 버전 선택의 중요성을 이해해요.
2026년 7월 기준 최신 문서 링크로 바로 들어갈 수 있어요.
📖
개념
스프링 문서는 "두 종류"예요
이 구분 하나가 문서 읽기의 절반이에요.
스프링 공식 문서를 처음 열면 "레퍼런스"와 "API(Javadoc)"라는 두 가지 링크가 보여요. 겉보기엔 둘 다 "문서"지만, 목적과 읽는 방식이 완전히 달라요. 이 둘을 헷갈리면 개념이 궁금한데 딱딱한 메서드 목록만 뒤지거나, 특정 메서드 시그니처가 궁금한데 긴 산문을 헤매게 돼요.
📘 ① 레퍼런스 문서 (Reference)
개념·설정·사용법을 산문(글) + 예제 코드로 풀어서 설명해요. "어떻게 쓰나 · 왜 이렇게 하나"를 알려주는 가이드북이에요. 개념 설명설정 방법예제 코드단원식 구성
예: "DI를 생성자 주입으로 하는 법", "트랜잭션 설정하는 법"
📗 ② Javadoc (API 명세)
클래스·메서드·어노테이션을 사전(dictionary)처럼 항목별로 정확히 명세해요. "정확히 무엇 · 어떤 파라미터 · 무엇을 반환"을 알려줘요. 클래스 목록메서드 시그니처파라미터·반환사전식
예: "@GetMapping의 속성", "RestTemplate의 메서드 목록"
🔤 "API"와 "API 문서"는 다른 말이에요API는 남이 내 코드를 쓸 수 있게 공개해 둔 "사용 창구"예요. 스프링이 제공하는 @RestController, RestTemplate.getForObject(...) 같은 클래스·메서드·어노테이션의 집합이 바로 스프링의 API죠. API 문서(= Javadoc)는 그 API를 글로 설명해 둔 명세서예요. "이 창구는 무엇을 받고 무엇을 돌려주는가"를 적어 둔 것.
스프링도 결국 자바라, 스프링의 API 문서는 자바 표준 도구인 Javadoc 형식으로 만들어져요. 그래서 여러분이 예전에 봤던 String·List의 Javadoc과 똑같은 화면 구조로 @RestController 같은 스프링 클래스도 찾아볼 수 있어요.
🧭
한 줄 정리.레퍼런스 = "어떻게/왜"를 설명하는 가이드북(산문+예제), Javadoc = "정확히 무엇"을 명세하는 사전(클래스·메서드 목록). 처음엔 레퍼런스로 개념을 잡고, 세부 시그니처가 궁금할 때 Javadoc으로 확인하는 흐름이 가장 좋아요.
문서 앞에서 헤매지 않으려면, 문서를 열기 전에 "내 질문이 개념·설정 쪽인가, 아니면 특정 클래스·메서드의 시그니처인가"를 먼저 나눠보면 돼요. 이 분기 하나로 90%는 정리됩니다.
🖼️ 그림으로 보기 — 궁금증 → 어느 문서로?
핵심은 질문의 성격이에요. "~하는 법 / 왜"는 왼쪽(레퍼런스), "이 메서드가 정확히 뭘 받고 돌려주지?"는 오른쪽(Javadoc). 보통 레퍼런스로 큰 그림을 잡고, 세부가 궁금할 때 Javadoc으로 확인하는 순서가 가장 빨라요.
이런 게 궁금하면
열어야 할 문서
"의존성 주입을 생성자로 하는 법이 궁금해"
📘 레퍼런스
"@Transactional은 어떤 상황에서 롤백하지?"
📘 레퍼런스 (개념) → 세부 속성은 📗 Javadoc
"@GetMapping에 어떤 속성(attribute)들이 있지?"
📗 Javadoc
"RestClient 클래스에 어떤 메서드가 있지?"
📗 Javadoc
"Spring Boot 프로젝트 처음 설정을 어떻게 시작하지?"
📘 레퍼런스 (Getting Started)
💡
실전 팁. IDE(IntelliJ 등)에서 클래스·메서드에 커서를 두고 Quick Documentation(단축키)을 누르면 그 자리에서 Javadoc이 떠요. 즉 Javadoc은 웹에서만 보는 게 아니라, 코딩 중에도 가장 자주 마주치는 문서예요.
🗺️
문서 지도
스프링 생태계는 "프로젝트마다 별도 문서"예요
스프링은 하나가 아니라 여러 프로젝트의 모음이라, 문서도 흩어져 있어요.
스프링을 처음 검색하면 문서가 여러 사이트로 흩어져 보여서 당황할 수 있어요. 이유는 간단해요 — Spring Framework, Spring Boot, Spring Data, Spring Security는 서로 다른 프로젝트라, 각자 자기 레퍼런스와 자기 Javadoc을 가져요. 그래서 "어느 프로젝트의 기능이냐"를 먼저 알면 문서 위치가 정해집니다.
🖼️ 그림으로 보기 — 프로젝트별 문서 지도
길을 잃으면 항상 spring.io/projects 로 돌아오세요. 거기서 프로젝트를 고르면 그 프로젝트의 Overview·Learn·Docs 로 들어가고, 다시 레퍼런스 와 API(Javadoc) 로 갈라져요. "어느 프로젝트냐"만 정하면 문서 위치가 자동으로 좁혀집니다.
🧭
길 찾기 순서. ① spring.io/projects 에서 프로젝트 선택 → ② 그 프로젝트 페이지에서 Learn 탭 → ③ Reference Doc.(레퍼런스) 또는 API Doc.(Javadoc) 선택 → ④ 화면에서 내 버전이 맞는지 확인. 이 4단계면 어떤 스프링 프로젝트든 문서에 도착해요.
🔬
화면 해부
레퍼런스 문서 화면, 부분별로 뜯어보기
어디에 무엇이 있는지 알면 한눈에 필요한 곳으로 갈 수 있어요.
레퍼런스 문서 화면은 어느 스프링 프로젝트든 거의 같은 뼈대예요. 좌측 목차(Core/Web/Data 등 큰 단원) · 상단의 버전 선택 · 본문(개념 설명 + 예제 코드). 아래 목업에 "여기서는 무엇을 보는지" 라벨을 붙여 뒀어요.
🖼️ 그림으로 보기 — 레퍼런스 문서 화면 해부
레퍼런스는 왼쪽에서 단원을 고르고, 본문에서 개념 → 예제 순으로 읽는 구조예요. 화면 우상단의 버전 선택 드롭다운이 늘 있으니, 읽기 전에 내 프로젝트 버전이 맞는지부터 확인하세요(다음 단원에서 자세히).
📗 참고 — Javadoc 화면은 이렇게 달라요
Javadoc은 왼쪽에 "패키지 → 클래스 목록"이 있고, 클래스를 고르면 본문에 그 클래스의 필드·생성자·메서드가 표로 나와요. 각 메서드는 시그니처(파라미터·반환형) + 짧은 설명 형태예요. 산문 가이드가 아니라 사전 항목이라고 생각하면 돼요.
즉 레퍼런스는 "읽는" 문서, Javadoc은 "찾아보는" 문서예요. 목적이 다르니 화면 구성도 다른 거죠.
⚠️
버전 주의
"내 프로젝트 버전에 맞는 문서"를 봐야 해요
스프링은 버전에 민감해요. 여기서 실수가 가장 많이 나와요.
스프링은 버전마다 어노테이션·설정 방식·기본값이 조금씩 달라요. 그래서 검색으로 찾은 블로그 글이 옛 버전 기준이면 "분명 똑같이 했는데 안 돼요" 상황이 생겨요. 항상 내 프로젝트가 쓰는 버전의 문서를 봐야 합니다. 그래서 레퍼런스 화면마다 버전 드롭다운이 있는 거예요.
💡
내 버전 확인법. Maven이면 pom.xml, Gradle이면 build.gradle에서 Spring Boot 버전을 보세요. Boot 버전을 알면 그에 묶인 Framework 버전도 정해져요(아래 표). 문서를 열 때 이 버전으로 드롭다운을 맞추면 됩니다.
기준 (2026년 7월)
버전
메모
Spring Framework (현재 최신)
7.0.x
모든 스프링의 핵심 뿌리
Spring Boot (현재 최신)
4.1
실무 프로젝트의 출발점
Spring Boot 계열
묶이는 Spring Framework
요구 Java
Boot 3.x
Framework 6
Java 17+
Boot 4.x (현재)
Framework 7
Java 17+ (최신 권장)
🔗
왜 짝이 정해져 있나요? Spring Boot는 자기가 어떤 Framework 버전 위에서 동작할지 미리 검증된 조합으로 배포해요. 그래서 "Boot 4.x면 Framework 7"처럼 버전이 세트로 움직여요. 이 짝만 기억하면, Boot 버전만 알아도 Framework 문서 버전을 바로 고를 수 있어요.
⚠️
가장 흔한 실수. 구글에서 "spring @어쩌구" 검색 → 상단에 뜬 문서가 몇 년 전 버전일 수 있어요. 문서를 열면 URL과 버전 드롭다운부터 확인하는 습관을 들이세요. URL에 /current/가 있으면 "현재 최신"을 뜻해요.
🔗
최신 링크
바로 들어가는 공식 문서 링크
아래는 모두 2026년 7월 기준입니다. 최신 버전은 계속 바뀌니, 항상 열린 화면의 버전을 확인하세요.
🗓️
2026년 7월 기준 링크예요. 스프링 문서 사이트는 docs.spring.io로 통합돼 있고, /current/가 들어간 주소는 항상 그 시점의 최신 버전으로 연결돼요.
즐겨찾기 추천.spring.io/projects(허브) 하나만 즐겨찾기 해 두면, 거기서 어떤 프로젝트든 레퍼런스·Javadoc으로 갈 수 있어요. 세부 URL은 버전마다 바뀌지만, 허브는 항상 최신으로 안내해 줘요.
🎁 번외 — start.spring.io(프로젝트 생성)와 문서의 관계 — 펼쳐 보기
start.spring.io(= Spring Initializr)는 새 스프링 프로젝트를 클릭 몇 번으로 생성해 주는 사이트예요. 여기서 고른 것들이 곧 "내가 어떤 문서를 봐야 하는지"를 결정해요.
① 버전 선택 = 봐야 할 문서 버전
Initializr에서 Spring Boot 버전을 고르죠(예: 4.1.x). 그러면 그에 묶인 Framework 버전(7)도 정해지고, 문서 드롭다운을 그 버전으로 맞춰야 한다는 뜻이 돼요.
② 의존성(Dependencies) 선택 = 봐야 할 프로젝트 문서
"Spring Web", "Spring Data JPA", "Spring Security"처럼 의존성을 추가하면, 각각이 앞서 본 별도 프로젝트예요. 즉 추가한 의존성마다 대응하는 레퍼런스/Javadoc이 있다는 뜻이에요.
start.spring.io 에서 고른 것 → 봐야 할 문서
────────────────────────────────────────────
Boot 4.1 선택 → Boot 4.x 레퍼런스 / Framework 7 문서
+ Spring Web 의존성 → Spring MVC(레퍼런스) · Web Javadoc
+ Spring Data JPA 의존성 → Spring Data JPA 문서
+ Spring Security 의존성 → Spring Security 문서
👉 핵심:프로젝트를 만드는 순간, 봐야 할 문서 목록도 함께 정해져요. 내가 추가한 의존성 = 내가 참고할 프로젝트 문서. 그래서 프로젝트 생성 화면과 문서 지도는 서로 짝이에요.
▲ 접기
🧠 이 부록 핵심 요약
스프링 문서는 두 종류 — 레퍼런스(개념·설정을 산문+예제로, "어떻게/왜") + Javadoc(클래스·메서드 사전식 명세, "정확히 무엇").
궁금증으로 문서를 골라요 — 개념·설정이면 레퍼런스, 특정 시그니처·속성이면 Javadoc.
스프링은 프로젝트마다 별도 문서(Framework·Boot·Data·Security). 길 잃으면 spring.io/projects로.
레퍼런스 화면 = 좌측 목차 + 버전 드롭다운 + 본문(개념+예제). Javadoc은 클래스 목록 + 메서드 표.
버전이 핵심 — 내 프로젝트 버전에 맞는 문서를 봐야 함. 2026.7 기준 Framework 7.0.x · Boot 4.1, Boot 4.x↔Framework 7 세트.