feat: API Rate Limiting 및 Swagger UI 구현 (#30) #31

seonkyu.kim · 2026-02-09T08:12:31Z

seonkyu.kim commented

2026-02-09 08:12:31 +00:00

📋 작업 요약

ASP.NET Core 내장 Rate Limiting 미들웨어 구현 (FixedWindow, IP 기반 분당 100회)
Swashbuckle.AspNetCore 6.9.0 기반 Swagger UI 추가 (브라우저에서 API 테스트 가능)
도메인별 API 문서 그룹 분리 (10개 그룹)
JWT Bearer 인증 UI 및 커스텀 헤더 자동 표시 필터

Closes #30

🛠️ 작업 내용 (Changes)

SPMS.API/Extensions/SwaggerExtensions.cs — AddSwaggerDocumentation() 확장 메서드 (도메인별 문서 그룹, JWT Bearer 인증, 커스텀 헤더 필터)
SPMS.API/Filters/SpmsHeaderOperationFilter.cs — X-Service-Code/X-API-KEY 커스텀 헤더 자동 표시 필터
SPMS.API/Extensions/ApplicationBuilderExtensions.cs — UseSwagger/UseSwaggerUI 등록, UseRateLimiter 활성화
SPMS.API/Program.cs — AddSwaggerDocumentation() + AddRateLimiter() 서비스 등록
SPMS.API/Controllers/PublicController.cs — GroupName, SwaggerOperation 어노테이션 적용
SPMS.API/SPMS.API.csproj — Swashbuckle 6.9.0 추가, Microsoft.AspNetCore.OpenApi 제거

📢 리뷰어 참고 사항 (To Reviewers)

Swashbuckle 버전 6.9.0 선택 이유: Swashbuckle 10.x는 Microsoft.OpenApi v2.x를 사용하는데, v2.x에서 Microsoft.OpenApi.Models 네임스페이스가 제거되어 빌드 에러 발생. 6.9.0은 Microsoft.OpenApi v1.6.14를 사용하여 안정적으로 동작
Microsoft.AspNetCore.OpenApi 10.0.2 제거: 이 패키지(.NET 10 Preview)가 Source Generator를 통해 Domain/Application/Infrastructure 클래스 라이브러리에까지 영향을 미쳐 Microsoft.AspNetCore.Mvc 등을 찾지 못하는 빌드 에러 유발. Swashbuckle이 Swagger UI를 제공하므로 불필요
Rate Limiting: IP 기반 FixedWindow(분당 100회). 추후 API Key 기반으로 확장 가능
Swagger UI는 Development 환경에서만 활성화됨

✅ 체크리스트 (Self Checklist)

빌드(Build)가 성공적으로 수행되었는가?
모든 단위 테스트(Unit Test)를 통과하였는가?
불필요한 로그나 주석을 제거하였는가?
컨벤션(Clean Architecture, Naming)을 준수하였는가?
기밀 정보(비밀번호, 키 등)가 하드코딩 되어있지 않은가?

📸 스크린샷 / 테스트 로그 (Screenshots/Logs)

빌드했습니다.
    경고 0개
    오류 0개

## 📋 작업 요약 - ASP.NET Core 내장 Rate Limiting 미들웨어 구현 (FixedWindow, IP 기반 분당 100회) - Swashbuckle.AspNetCore 6.9.0 기반 Swagger UI 추가 (브라우저에서 API 테스트 가능) - 도메인별 API 문서 그룹 분리 (10개 그룹) - JWT Bearer 인증 UI 및 커스텀 헤더 자동 표시 필터 ## 🔗 관련 이슈 (Related Issues) Closes #30 ## 🛠️ 작업 내용 (Changes) - [x] `SPMS.API/Extensions/SwaggerExtensions.cs` — AddSwaggerDocumentation() 확장 메서드 (도메인별 문서 그룹, JWT Bearer 인증, 커스텀 헤더 필터) - [x] `SPMS.API/Filters/SpmsHeaderOperationFilter.cs` — X-Service-Code/X-API-KEY 커스텀 헤더 자동 표시 필터 - [x] `SPMS.API/Extensions/ApplicationBuilderExtensions.cs` — UseSwagger/UseSwaggerUI 등록, UseRateLimiter 활성화 - [x] `SPMS.API/Program.cs` — AddSwaggerDocumentation() + AddRateLimiter() 서비스 등록 - [x] `SPMS.API/Controllers/PublicController.cs` — GroupName, SwaggerOperation 어노테이션 적용 - [x] `SPMS.API/SPMS.API.csproj` — Swashbuckle 6.9.0 추가, Microsoft.AspNetCore.OpenApi 제거 ## 📢 리뷰어 참고 사항 (To Reviewers) - **Swashbuckle 버전 6.9.0 선택 이유**: Swashbuckle 10.x는 Microsoft.OpenApi v2.x를 사용하는데, v2.x에서 `Microsoft.OpenApi.Models` 네임스페이스가 제거되어 빌드 에러 발생. 6.9.0은 Microsoft.OpenApi v1.6.14를 사용하여 안정적으로 동작 - **Microsoft.AspNetCore.OpenApi 10.0.2 제거**: 이 패키지(.NET 10 Preview)가 Source Generator를 통해 Domain/Application/Infrastructure 클래스 라이브러리에까지 영향을 미쳐 `Microsoft.AspNetCore.Mvc` 등을 찾지 못하는 빌드 에러 유발. Swashbuckle이 Swagger UI를 제공하므로 불필요 - Rate Limiting: IP 기반 FixedWindow(분당 100회). 추후 API Key 기반으로 확장 가능 - Swagger UI는 Development 환경에서만 활성화됨 ## ✅ 체크리스트 (Self Checklist) - [x] 빌드(Build)가 성공적으로 수행되었는가? - [x] 모든 단위 테스트(Unit Test)를 통과하였는가? - [x] 불필요한 로그나 주석을 제거하였는가? - [x] 컨벤션(Clean Architecture, Naming)을 준수하였는가? - [x] 기밀 정보(비밀번호, 키 등)가 하드코딩 되어있지 않은가? ## 📸 스크린샷 / 테스트 로그 (Screenshots/Logs) ``` 빌드했습니다. 경고 0개 오류 0개 ```

seonkyu.kim added 1 commit 2026-02-09 08:12:33 +00:00

feat: API Rate Limiting 및 Swagger UI 구현 (#30 ) 58b94c6298

- ASP.NET Core 내장 Rate Limiting (FixedWindow, IP 기반 분당 100회)
- 한도 초과 시 HTTP 429 + ApiResponse(에러코드 106) 반환
- Swashbuckle.AspNetCore 6.9.0 기반 Swagger UI 추가
- 도메인별 API 문서 그룹 (all, public, auth 등 10개)
- JWT Bearer 인증 UI (Authorize 버튼)
- X-Service-Code/X-API-KEY 커스텀 헤더 자동 표시 필터
- Microsoft.AspNetCore.OpenApi 제거 (Swashbuckle과 호환 충돌)

Closes #30

seonkyu.kim added the

labels 2026-02-09 08:12:48 +00:00

seonkyu.kim self-assigned this 2026-02-09 08:12:55 +00:00

seonkyu.kim added this to the Phase 1: 인프라 & 공통 모듈 milestone 2026-02-09 08:12:56 +00:00

seonkyu.kim requested review from Owners 2026-02-09 08:13:01 +00:00

seonkyu.kim merged commit 4270e70f09 into develop