Swagger(Web API 문서) 적용

1️⃣ Swagger란?

• API 명세를 자동으로 문서화해주는 도구.
• 개발자는 API 만들 때 @RestController, @GetMapping 등 스프링 애노테이션만 써도 Swagger가 자동으로 읽어서 정리해줌.
• API를 테스트/공유/디버그할 때 엄청 편리함

 

---

2️⃣ 적용 방법

Build.gradle 추가

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:버전'

여기까지 해주면 ...

별도 설정 없이도 기본으로 API 문서 생성됨 (특별히 API 설명을 더 하고 싶으면 @Operation, @ApiResponses 같은 걸 붙이면 됨.)

 

---

3️⃣ 접속 & 확인 방법

• 👉 접속 주소:
  • Swagger UI 페이지:
    http://localhost:8081/swagger-ui/index.html
  • API JSON 문서:
    http://localhost:8081/v3/api-docs
• 접속 시 API 목록이 잘 뜨면 완료!

 

---

4️⃣ 누가 어떨 때 사용하나요?

✅ 프론트엔드/앱 개발자가 이렇게 씀

• 이 화면을 열고 API 경로, 요청 방식(GET/POST 등), 파라미터, 응답 형식을 보고 개발함.
• 필요한 데이터만 잘 전달되면 서버랑 프론트 협업이 매끄러워짐.

---

5️⃣ 주의할 점

• 보안 문제 때문에 프로덕션(운영 서버)에서는 Swagger를 끄는 경우가 많음.
  • springdoc.api-docs.enabled=false
• 내부 테스트용으로만 두고, 외부엔 숨기기.