Swagger UI로 API 문서 자동화 & 협업 꿀팁

1. 왜 Swagger UI인가?

• 변경‧추가 즉시 문서 갱신: Controller·DTO에 애너테이션만 붙이면 최신 OpenAPI 스펙이 자동 생성됩니다.
• 개발·QA·프런트 모두 같은 화면: UI에서 엔드포인트·파라미터·예시 응답을 확인하고 바로 호출까지 가능해 커뮤니케이션 비용이 급감합니다.
• Postman‧SDK로 원클릭 공유: 스펙을 그대로 가져가 회귀 테스트나 클라이언트 코드 생성에 재사용할 수 있습니다.

---

2. 스프링 부트에 springdoc-openapi 적용

// build.gradle
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0'

// SwaggerConfig.java
@OpenAPIDefinition(
    info = @Info(title = "Article API",
                 version = "v1",
                 description = "CRUD 예제용 문서"))
public class SwaggerConfig {}

• 실행 후 /swagger-ui/index.html로 접속하면 API 명세서가 뚝딱!
• 다국어 UI가 필요하면 springdoc.swagger-ui.display-lang=ko를 application.yml에 추가.

---

3. 팀 협업 레벨 업 팁 7가지

1. API 그룹화로 가독성↑
   @Tag(name="Article")처럼 태그를 붙이면 카테고리별로 접이식 뷰가 생성돼 프런트 쪽에서 원하는 엔드포인트를 바로 찾을 수 있습니다.
2. YAML 소스 Versioning
   springdoc-openapi는 /v3/api-docs.yaml을 뱉습니다. curl로 받아 repo /docs 폴더에 커밋하면 PR diff만으로 스펙 변경을 리뷰할 수 있어요.
3. SwaggerHub로 실시간 코멘트
   YAML을 SwaggerHub에 올리면 팀원이 브라우저에서 주석 달고, 클라이언트 SDK(JavaScript·TypeScript 등)를 버튼 하나로 생성할 수 있습니다.
4. Postman 한-방 가져오기
   Postman → Import → “Link”에 /v3/api-docs.yaml URL을 붙이면 즉시 컬렉션이 만들어집니다. 테스트 스크립트·환경변수만 조금 손보면 회귀 테스트 세트 완성!
5. 프로필별 노출 제어
   application-prod.yml에 
   

   springdoc:
     swagger-ui.enabled: false
     api-docs.enabled: false

   
   넣으면 운영 환경에서는 Swagger가 잠금 처리되어 보안 걱정 끝.
6. CSRF·인증 토큰 전역 설정
   Swagger UI 상단 “Authorize” 버튼에 JWT Bearer 스키마를 등록하면 프런트엔드·QA가 토큰을 따로 붙일 필요 없이 바로 호출해 볼 수 있습니다.
7. CI 파이프라인에 문서 스냅샷
   Gradle openapi-generator 플러그인으로 빌드 단계마다 HTML 정적 문서를 생성 → S3 혹은 GitHub Pages에 배포하면 외부 파트너도 읽을 수 있는 공식 문서 포털이 완성됩니다.

 

---

4. 흔히 놓치는 설정 Check-list

• 응답 예시(example) 깔끔하게: DTO 필드마다 @Schema(description="글 제목", example="새 글")를 달면 Swagger UI가 예시 값을 자동 채워줍니다.
• 404·500 등 공통 응답 코드: @ApiResponse(responseCode="404", description="Not Found")를 Controller 레벨에 선언해 두면 누구나 실패 시나리오까지 한눈에 확인.
• OAuth2 인증 흐름 표시: @SecurityScheme(type = SecuritySchemeType.OAUTH2, …)로 토큰 발급 URL을 설정해 두면 버튼 하나로 로그인→API 호출이 됩니다.
• 모놀리식→마이크로서비스로 분리 시: 서비스별 그룹 값을 springdoc.group-configs로 정의하면 /swagger-ui/{group-name} 형태로 UI를 쪼갤 수 있어요.

---

5. “내일 당장 써먹는” 실전 꿀팁

• 단축키 Ctrl+K: Swagger UI에서 검색창 커서 바로 이동 → 함수 검색 속도 증가
• Try it out → Curl 복사: QA가 재현용 스크립트를 Notion에 붙여 넣으면 신입도 동일 환경 테스트가 가능
• Trash Endpoint 숨기기: @Hidden을 붙여 내부 관리용 API를 UI에서 제거, 깔끔!

---

6. 마무리

Swagger UI는 “코드 변경 ⇄ 문서 업데이트” 루프를 완전히 자동화해 줍니다. 여기에 버전 관리·Postman·SwaggerHub 연동까지 더하면 백엔드·프런트·QA가 같은 언어로 대화하게 되죠. 내일은 OpenAPI Generator로 클라이언트 SDK를 뽑아, 프런트 개발 속도를 2배로 끌어올려 봅시다!