[Docs] : 스웨거 명세 수정 #68
Conversation
- 스웨거에서 multipart/form-data로 요청을 보낼 수 있도록 dto의 content type을 명시
- 프로젝트에 맞는 제목과 설명으로 수정
Walkthrough기부 등록 엔드포인트의 Swagger 어노테이션 및 요청 처리 방식을 업데이트하고, API 문서 제목과 설명을 변경했습니다. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes
Possibly related issues
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Tip 📝 Customizable high-level summaries are now available in beta!You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.
Example instruction:
Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Test Results9 tests 9 ✅ 5s ⏱️ Results for commit bd135a9. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
src/main/java/com/donet/donet/donation/adapter/in/web/CreateDonationController.java (1)
40-41: @parameter 어노테이션을 개선하면 더 명확한 문서화가 가능합니다.기본적인 접근 방식은 올바르지만,
@Parameter어노테이션에description속성을 추가하면 Swagger UI에서 각 파라미터의 용도가 더 명확해집니다.다음과 같이 개선할 수 있습니다:
- @Parameter @RequestPart(required = false) List<MultipartFile> images, - @Parameter @RequestPart CreateDonationRequest request + @Parameter(description = "기부 관련 이미지 파일 목록") @RequestPart(required = false) List<MultipartFile> images, + @Parameter(description = "기부 생성 요청 정보 (JSON)") @RequestPart CreateDonationRequest request
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
src/main/java/com/donet/donet/donation/adapter/in/web/CreateDonationController.java(2 hunks)src/main/java/com/donet/donet/global/config/SwaggerConfig.java(1 hunks)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: build
🔇 Additional comments (3)
src/main/java/com/donet/donet/global/config/SwaggerConfig.java (1)
37-38: LGTM! API 문서 메타데이터 업데이트가 적절합니다.API 명세서 제목과 설명이 프로젝트명에 맞게 업데이트되었습니다.
src/main/java/com/donet/donet/donation/adapter/in/web/CreateDonationController.java (2)
11-15: LGTM! 필요한 import가 올바르게 추가되었습니다.OpenAPI 어노테이션과 MediaType이 하단의 Swagger 명세 개선을 위해 적절히 추가되었습니다.
38-38: LGTM! multipart/form-data content type이 명시적으로 선언되었습니다.
consumes속성을 통해 엔드포인트가 multipart/form-data를 처리함을 명확히 했습니다. 이는 Swagger 명세 생성과 Spring의 요청 처리 모두에 도움이 됩니다.
| @RequestBody(content = @Content( | ||
| encoding = @Encoding(name = "request", contentType = MediaType.APPLICATION_JSON_VALUE))) |
There was a problem hiding this comment.
🧩 Analysis chain
메서드 레벨의 @RequestBody 어노테이션 사용 확인이 필요합니다.
OpenAPI의 @RequestBody 어노테이션이 메서드 레벨에서 사용되었는데, @RequestPart와 함께 사용할 때 SpringDoc이 이를 올바르게 처리하는지 확인이 필요합니다. 일반적으로 multipart/form-data 엔드포인트에서는 각 파트에 대한 설명이 @Parameter 어노테이션으로 충분할 수 있습니다.
다음 사항을 검증해주세요:
- Swagger UI에서 API를 호출했을 때 실제로 400 에러가 해결되는지 확인
- Swagger UI에서 생성된 요청 스키마가 올바른지 확인 (JSON 파트와 파일 파트가 제대로 구분되는지)
🏁 Script executed:
#!/bin/bash
# SpringDoc에서 메서드 레벨 @RequestBody와 @RequestPart 조합 사용 예시 검색
rg -nP --type=java -C3 '@RequestBody.*@Content.*multipart' Length of output: 0
추가 검증이 필요합니다. 먼저 실제 파일 내용을 확인하겠습니다.
---
🏁 Script executed:
```shell
#!/bin/bash
# CreateDonationController.java 파일 확인 (줄 20-50 범위)
cat src/main/java/com/donet/donet/donation/adapter/in/web/CreateDonationController.java | head -60 | tail -41
Length of output: 1610
🏁 Script executed:
#!/bin/bash
# 메서드 전체 구조 확인 - @RequestPart 파라미터 찾기
rg -nP --type=java -A20 'CreateDonationController' src/main/java/com/donet/donet/donation/adapter/in/web/CreateDonationController.javaLength of output: 1105
🏁 Script executed:
#!/bin/bash
# multipart 관련 다른 어노테이션 패턴 검색
rg -nP --type=java '@RequestPart|@RequestBody|@Encoding' src/main/java/com/donet/donet/donation/adapter/in/web/CreateDonationController.javaLength of output: 363
🏁 Script executed:
#!/bin/bash
# 프로젝트의 Spring Boot / SpringDoc 버전 확인
cat pom.xml | grep -A5 -B5 'springdoc\|spring-boot' | head -40Length of output: 39
빌드 파일과 SpringDoc 문서를 확인하겠습니다.
🏁 Script executed:
#!/bin/bash
# 빌드 파일 찾기
fd -name 'pom.xml' -o -name 'build.gradle' -o -name 'build.gradle.kts'Length of output: 230
🏁 Script executed:
#!/bin/bash
# 프로젝트 루트의 모든 설정 파일 확인
ls -la | grep -E '\.(xml|gradle|toml)$|pom\.|build\.'Length of output: 130
🏁 Script executed:
#!/bin/bash
# SpringDoc 관련 의존성 찾기 (일반적인 위치들)
find . -type f -name '*.xml' -o -name 'gradle*' 2>/dev/null | head -10Length of output: 111
🌐 Web query:
SpringDoc OpenAPI @RequestBody multipart form data @RequestPart annotation
💡 Result:
Short answer: use @RequestPart (not @RequestBody) for multipart parts — one part as MultipartFile and another part as a POJO — annotate controller with consumes = MediaType.MULTIPART_FORM_DATA_VALUE. springdoc-openapi will then generate a multipart/form-data requestBody with a file property (type: string, format: binary) and a POJO property (JSON schema). Example:
- Controller:
@PostMapping(path = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public ResponseEntity upload(
@RequestPart("file") MultipartFile file,
@RequestPart("meta") MyMetaDto meta) { ... }
Notes:
- Do NOT use @RequestBody for a multipart JSON part — @RequestPart uses HttpMessageConverters and honors the part Content-Type (application/json) while @RequestParam does simple conversion. [1][2][3]
- springdoc maps multipart parts into the requestBody schema (file -> format: binary; POJO -> $ref) and may choose @RequestPart vs @RequestParam based on encoding/contentType information. If you see incorrect generation, check springdoc issues and ensure parts include proper Content-Type (application/json) when sending requests. [4][5]
References:
- Spring Framework docs — @RequestPart explanation and file-with-JSON example. [2]
- Spring @RequestPart Javadoc (behavior with HttpMessageConverters). [3]
- springdoc-openapi project docs / behavior for multipart and examples (how it generates multipart/form-data schema). [5]
- springdoc GitHub issues discussing multipart JSON and mixed parts. [1][4]
SpringDoc 버전을 확인한 후 최종 검증을 완료하겠습니다.
---
🏁 Script executed:
```shell
#!/bin/bash
# build.gradle에서 springdoc 버전 확인
cat build.gradle | grep -A2 -B2 'springdoc\|openapi'
Length of output: 102
메서드 레벨의 @RequestBody 어노테이션을 제거해야 합니다.
Multipart 엔드포인트에서 @RequestBody를 사용하는 것은 잘못된 관행입니다. @RequestPart를 multipart 파트에 사용해야 하며, @RequestBody는 multipart에 사용하면 안 됩니다. 현재 코드의 @RequestPart 파라미터 정의(lines 40-41)는 올바르며, SpringDoc이 이를 자동으로 올바른 multipart/form-data 스키마로 생성합니다.
수정 사항: lines 29-30의 @RequestBody(content = @Content(...)) 어노테이션을 제거하세요. @RequestPart 파라미터 정의와 @PostMapping의 consumes = MediaType.MULTIPART_FORM_DATA_VALUE만으로 충분합니다.
🤖 Prompt for AI Agents
In
src/main/java/com/donet/donet/donation/adapter/in/web/CreateDonationController.java
around lines 29-30, remove the method-level @RequestBody(...) OpenAPI
annotation; using @RequestBody on a multipart endpoint is incorrect—keep the
existing @RequestPart parameters (lines 40-41) and the @PostMapping(consumes =
MediaType.MULTIPART_FORM_DATA_VALUE) only so SpringDoc generates the correct
multipart/form-data schema.
There was a problem hiding this comment.
Seems like the humans are having a chat. I'll hop back into my burrow for now. If you need me again, just tag @coderabbitai in a new comment, and I'll come hopping out!
📌 PR 설명
스웨거에서 기부 기록 저장하기 API에 요청했을 때 400에러가 뜨는 문제를 수정했습니다.
스웨거 제목과 설명도 수정했습니다.
✅ 작업 내용
🔍 리뷰 요청 사항
📷 스크린샷 (선택)
Summary by CodeRabbit
릴리스 노트
개선사항
문서화
✏️ Tip: You can customize this high-level summary in your review settings.