Open
Conversation
📝 WalkthroughWalkthroughEight new API documentation files are added for badge operations—covering creation, deletion, retrieval, assignment, and modification—along with a Table of Contents update. No functional code changes are introduced. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 28
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@badge/assign.md`:
- Around line 35-49: Add documented error responses to the "응답 (Response)"
section in badge/assign.md: enumerate status codes 400, 401, 403, 404, and 409
with brief meanings (e.g., 400 Bad Request — empty/invalid member IDs, 401
Unauthorized — missing/invalid JWT, 403 Forbidden — insufficient permissions,
404 Not Found — badge or member IDs do not exist, 409 Conflict — members already
have the badge), and include at least one example JSON error payload for each
case similar to the existing success example so consumers can see
code/message/data fields for error responses.
- Around line 28-31: The MemberBadgeReqDTO's memberIds field is under-documented
and likely mis-marked as optional; update the spec for MemberBadgeReqDTO: change
the 필수 column to required for memberIds, replace the placeholder description
with a meaningful Korean description such as "배지를 부여할 회원 ID 목록", and add short
notes in the endpoint/body docs about behavior when the list is empty (e.g.,
reject request with 400 or no-op) and idempotency (e.g., assigning an
already-held badge is ignored or returns existing state). Also mention whether
duplicates are allowed and how they are handled.
- Around line 42-49: Update the response example in badge/assign.md so the
"data" field returns assignment results instead of null: populate "data" with at
least an assignedCount and optionally a memberIds array (e.g., "assignedCount":
<n>, "memberIds": [<ids>]) to reflect which members were successfully assigned
the badge; ensure the example JSON under the "응답 예시" section replaces "data":
null with this structured result so consumers can see operation outcome.
In `@badge/delete.md`:
- Around line 30-44: The Response section in badge/delete.md currently only
documents the 200 success case; add documented error responses for 401
Unauthorized (missing/invalid JWT), 403 Forbidden (insufficient
role/non-MANAGER), 404 Not Found (badge ID not found), and 409 Conflict (badge
cannot be deleted due to constraints), each with a short description and an
example JSON body similar to the success example (code, message, data), and
include the corresponding HTTP status codes under the response table so
consumers can see both status and example payloads.
- Around line 1-44: Update the badge/delete.md documentation for the DELETE
/v1/admin/badges/{badgeId} endpoint to explicitly state the business effects:
describe whether deletion is soft or hard (e.g., soft-delete flag or physical
removal), what happens to members who currently have the badge (e.g., badge
removed from member profiles, preserved history, or left unchanged), list any
constraints that prevent deletion (e.g., cannot delete if badge is assigned,
requires unassignment, or only deletable by MANAGER role), and clarify how the
response (the example with "data": null and 200 OK) should be interpreted in
each case; include these details under the "개요" or a new "영향 및 제약" section so
API consumers can understand impact and preconditions for DELETE
/v1/admin/badges/{badgeId}.
In `@badge/get-badge-list.md`:
- Around line 31-53: Add documented error responses to the "응답 (Response)"
section for the get-badge-list API: describe 400 Bad Request for invalid
pagination parameters (e.g., negative page, invalid size) including a brief
message and example body referencing BadgeSliceResDTO context, 401 Unauthorized
for missing/invalid JWT with example message and suggested WWW-Authenticate
header, and 403 Forbidden for insufficient permissions (non-MANAGER) with
example message; update the "응답 예시" area to include JSON examples for each error
case and ensure each entry lists HTTP Status, 의미, and a short description of the
error condition.
- Around line 38-44: Add a concrete definition for BadgeResDTO and improve
descriptions in the BadgeSliceResDTO section: document the content element as
List<BadgeResDTO> and then define BadgeResDTO with fields such as badgeId
(Integer, unique id), name (String), imageUrl (String), description (String),
requirement (String), createdAt (Timestamp), and any other relevant fields, and
update each column's 설명 to clearly describe purpose/format (e.g., badgeId:
unique badge identifier, imageUrl: absolute URL to badge image, createdAt:
ISO8601 timestamp); ensure the BadgeSliceResDTO table rows (content, pageNumber,
pageSize, hasNext) have clearer descriptions as well referencing BadgeResDTO for
content.
- Around line 23-27: Update the pagination docs for the query parameters 'page'
and 'size' in badge/get-badge-list.md to explicitly state whether pagination is
zero- or one-indexed (e.g., page=0 for first page), add allowed range for 'size'
(e.g., min and max values or recommended defaults such as min=1, max=100),
document the default values instead of "-" (e.g., page=0, size=20), and describe
behavior when 'page' exceeds available pages (e.g., returns empty list and HTTP
200, or HTTP 4xx/5xx if applicable); ensure the table row entries for page and
size are updated to include these details and any validation rules.
- Around line 46-53: The response example currently returns "data": null for a
paginated GET; replace that with a pagination object instead: set "data" to an
object containing "content" (an array of badge objects with fields badgeId,
name, imageUrl, description, requirement, createdAt) and pagination metadata
fields "pageNumber", "pageSize", and "hasNext" so the example shows actual
paginated results rather than null.
In `@badge/get-member-badges.md`:
- Around line 30-49: Update the API doc in badge/get-member-badges.md to include
documented error responses: add 401 Unauthorized (missing/invalid JWT), 403
Forbidden (insufficient permission to view another member's badges), and 404 Not
Found (member ID does not exist) alongside the existing 200 response; place them
under the "응답 (Response)" section and add example JSON bodies for each error
case consistent with the current response schema (code, message, data) so
clients can see exact status codes and sample payloads for get-member-badges.
- Around line 42-49: The response example in badge/get-member-badges.md
incorrectly shows "data": null for a GET that returns badges; update the example
JSON so "data" is an array of badge objects (not null) and include
representative fields such as badgeId, name, imageUrl, description, and
acquiredAt to illustrate the structure consumers should expect; ensure the
example shows multiple items (e.g., two badge objects) to demonstrate the array
response shape.
- Around line 37-40: Fix the syntax error in the Body header by closing the
generic bracket to read "List<MemberOwnedBadgeResDTO>" and expand the Body
section to document the MemberOwnedBadgeResDTO structure: add a table listing
each field (e.g., badgeId: string/int, name: string, imageUrl: string,
description: string, earnedAt: datetime, isActive: boolean) with types and short
explanations; ensure the header references the correct DTO name
MemberOwnedBadgeResDTO and include any optional vs required flags and example
values where appropriate.
In `@badge/get-members.md`:
- Around line 43-50: Add a detailed definition for MemberBadgeResDTO and improve
field descriptions in MemberBadgeSliceResDTO: define MemberBadgeResDTO with
fields such as memberId (Integer), name (String), profileImage (String, URL),
assignedAt (ISO8601 timestamp) and any other relevant properties, then update
the MemberBadgeSliceResDTO table entry for content to reference the new
MemberBadgeResDTO schema and replace vague labels (e.g., "content",
"pageNumber", "pageSize", "hasNext") with clearer descriptions explaining each
field's meaning and types so API consumers know the exact structure of each
member object.
- Around line 36-58: Add documented error responses to the existing response
section for the badge membership endpoint: list the 400 Bad Request for invalid
pagination parameters (negative page, invalid size) referencing
MemberBadgeSliceResDTO pagination fields (pageNumber/pageSize), 401 Unauthorized
for missing/invalid JWT, 403 Forbidden for insufficient permissions (non-MANAGER
role), and 404 Not Found when the requested badge ID does not exist (Badge not
found). For each status include a short description and example JSON body
matching the existing response shape (code/message/data) and ensure keys align
with MemberBadgeResDTO and MemberBadgeSliceResDTO where applicable.
- Around line 28-32: Update the Query Parameters section for page and size to
state pagination indexing (e.g., page is zero-indexed), add explicit default
values (e.g., page=0, size=20) instead of "-", document allowed range for size
(min and max, e.g., min=1, max=100) and what happens when page exceeds available
pages (e.g., returns empty list with HTTP 200 or specific error), and include
these details next to the "page" and "size" entries in the badge/get-members.md
Query Parameters table so consumers can see indexing, defaults, min/max and
overflow behavior.
- Around line 51-58: The response example currently shows "data": null for the
paginated GET endpoint; update the JSON example in the response block to show a
realistic paginated payload instead of null by replacing the null with an object
containing "content" (array of member objects with fields like memberId, name,
email, assignedAt) and pagination metadata ("pageNumber", "pageSize",
"hasNext"). Edit the JSON example in badge/get-members.md (the response example
block) so consumers see the expected structure for functions that return
paginated members.
In `@badge/post-create.md`:
- Around line 33-47: Update the "응답 (Response)" section in badge/post-create.md
to include documented error responses: add entries for 400 Bad Request
(validation errors/missing fields), 401 Unauthorized (missing/invalid JWT), 403
Forbidden (non-MANAGER insufficient permissions), and 409 Conflict (badge name
already exists) with short descriptions and example JSON bodies matching the
successful response shape (e.g., {"code": <status>, "message": "<error
message>", "data": null}); ensure these new error cases appear alongside the
existing 201 Created example under the same "응답 (Response)" heading so consumers
of the POST /badge (post-create.md) spec can see both success and failure
responses.
- Around line 40-47: Update the POST response example so the "data" field
returns the created badge object instead of null: replace the null "data" with
an object containing the generated badge ID and metadata (e.g., badgeId, name,
imageUrl, description, requirement, createdAt) so clients receive the newly
created resource immediately; ensure the example JSON in badge/post-create.md
reflects these properties and a 201 status.
- Around line 23-29: The POST create badge contract currently marks all
BadgeCreateReqDTO fields optional and uses tautological field descriptions;
update the BadgeCreateReqDTO docs and validation so that at minimum the name
field is required (set 필수 to Y) and, optionally, consider making imageUrl
required if your domain needs it; replace the description column entries with
meaningful explanations for name (display name of the badge), imageUrl (public
URL for badge image), description (short summary shown to users), and
requirement (criteria to earn the badge); also ensure the underlying
BadgeCreateReqDTO validation/annotations reflect the required change so runtime
validation matches the docs.
In `@badge/remove.md`:
- Around line 28-31: Update the MemberBadgeReqDTO documentation: change the
memberIds field description from a tautology to a clear Korean description like
"배지를 회수할 회원 ID 목록", mark memberIds as required (remove the optional "X"), and
add a short note clarifying behavior when the list is empty (reject request or
return 400) and idempotency semantics (operation is a no-op for members who
don't have the badge and should not error). Ensure these changes are applied to
the MemberBadgeReqDTO section and any API behavior notes that reference
memberIds.
- Around line 35-49: The response documentation under the "응답 (Response)"
section in badge/remove.md only shows the 200 success case and lacks error-case
documentation; update this section to add the listed error scenarios (400 Bad
Request for empty/invalid member IDs, 401 Unauthorized for missing/invalid JWT,
403 Forbidden for insufficient permissions, 404 Not Found for missing badge or
member IDs, and 404 Not Found or a specific error for members who don't have the
badge if the operation is non‑idempotent), include a short description for each
status code, and provide example JSON error response bodies analogous to the
existing success example so callers know the error shape and messages.
- Around line 42-49: Update the DELETE response example in badge/remove.md so it
returns an operation result instead of null: modify the JSON example inside the
"응답 예시" block to replace "data": null with an object containing fields like
"removedCount" and "memberIds" (e.g., removedCount: number, memberIds: array of
ids) so consumers can see how many items were removed and which member IDs were
affected.
In `@badge/update.md`:
- Around line 38-52: Add missing error-case documentation under the "응답
(Response)" section in badge/update.md: list and describe the HTTP error
responses (400 Bad Request for invalid input, 401 Unauthorized for
missing/invalid JWT, 403 Forbidden for non-MANAGER permission, 404 Not Found for
nonexistent badge ID, 422 Unprocessable Entity when no update fields provided)
and include an example JSON response for each status similar to the existing
success example to guide API consumers.
- Around line 45-52: The example response for the PATCH badge endpoint currently
returns "data": null; update the example in badge/update.md to return the
updated badge object instead (include fields such as badgeId, name, imageUrl,
description, requirement) so consumers can verify the update—replace the null
data with a JSON object showing the updated badge values as in the suggested
example.
- Around line 28-34: The current BadgeUpdateReqDTO field descriptions are
placeholders; update the docs for BadgeUpdateReqDTO to replace each field's
description with clear purpose, format constraints, examples, and validation
rules: for name describe business meaning (display/title for badge), max length
(e.g., 50 chars), allowed characters (letters, digits, spaces, hyphens), and
example; for imageUrl state it must be a valid HTTPS URL, max length (e.g.,
2048), allowed formats (png,jpg,svg) and example; for description explain usage
(short human-readable summary), max length (e.g., 250), prohibited content rules
and example; for requirement explain the badge unlock criteria (plain text or
markdown), max length (e.g., 1000), any structured pattern or keys if required
and example; include explicit validation rules (required/optional, trimming,
uniqueness constraints) for each field and add representative examples for API
consumers.
In `@SUMMARY.md`:
- Line 98: The summary references an inconsistent file name "post-create.md"
which uses an HTTP method prefix while sibling files use verbs like "delete.md",
"update.md", "assign.md", "remove.md"; rename "post-create.md" to "create.md"
and update any links in SUMMARY.md and other docs that reference
"post-create.md" to the new name (ensure the TOC entry "* [배지
생성](badge/create.md)" replaces the current link), or alternatively apply the
same "post-" prefix to all badge endpoint files—pick one convention and make
filenames and all cross-references consistent across the badge docs.
- Line 96: Fix the Korean spelling inconsistency by replacing "뱃지" with the
standard "배지" everywhere — specifically update the bullet text "* [뱃지
부여](badge/create.md)" and the corresponding section header and occurrences in
the badge section (the lines that currently use "뱃지") so all instances read "배지"
(e.g., change "뱃지 부여" to "배지 부여" and any headings or list items in the badge
section to use "배지").
- Line 96: There are duplicate SUMMARY entries titled "뱃지 부여" pointing to
badge/create.md and "배지 부여" pointing to badge/assign.md causing confusion;
update SUMMARY.md to either consolidate into one entry that links to
badge/assign.md (if that document is the assignment endpoint) and change the
badge/create.md heading/link to "뱃지 생성" (or similar) to reflect badge entity
creation, or clearly rename/update both link texts so one reads "뱃지 생성" ->
badge/create.md and the other reads "뱃지 부여" -> badge/assign.md to clarify their
distinct purposes.
ℹ️ Review info
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (9)
SUMMARY.mdbadge/assign.mdbadge/delete.mdbadge/get-badge-list.mdbadge/get-member-badges.mdbadge/get-members.mdbadge/post-create.mdbadge/remove.mdbadge/update.md
Comment on lines
+28
to
+31
| **Body (MemberBadgeReqDTO)** | ||
| | Key | Type | 설명 | 필수 | | ||
| |-----|------|------|------| | ||
| | memberIds | List<Long> | memberIds | X | |
There was a problem hiding this comment.
Field description is inadequate and "필수" marking may be incorrect.
The description "memberIds" → "memberIds" provides no value. Additionally, marking this field as optional (X) is questionable—assigning a badge without specifying any members would be meaningless.
Consider:
- Clarifying whether the field should be required
- Adding meaningful description (e.g., "배지를 부여할 회원 ID 목록")
- Documenting behavior when list is empty
- Specifying idempotency (what happens if a member already has the badge?)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@badge/assign.md` around lines 28 - 31, The MemberBadgeReqDTO's memberIds
field is under-documented and likely mis-marked as optional; update the spec for
MemberBadgeReqDTO: change the 필수 column to required for memberIds, replace the
placeholder description with a meaningful Korean description such as "배지를 부여할 회원
ID 목록", and add short notes in the endpoint/body docs about behavior when the
list is empty (e.g., reject request with 400 or no-op) and idempotency (e.g.,
assigning an already-held badge is ignored or returns existing state). Also
mention whether duplicates are allowed and how they are handled.
Comment on lines
+35
to
+49
| ### 응답 (Response) | ||
|
|
||
| **성공** | ||
| | HTTP Status | 의미 | | ||
| |-------------|------| | ||
| | 201 Created | 요청 성공 | | ||
|
|
||
| **응답 예시** | ||
| ```json | ||
| { | ||
| "code": 201, | ||
| "message": "요청이 성공적으로 처리되었습니다.", | ||
| "data": null | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Missing error case documentation.
Document error scenarios such as:
- 400 Bad Request: Empty or invalid member IDs
- 401 Unauthorized: Missing or invalid JWT
- 403 Forbidden: Insufficient permissions
- 404 Not Found: Badge ID or member ID(s) do not exist
- 409 Conflict: Members already have the badge (if not idempotent)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@badge/assign.md` around lines 35 - 49, Add documented error responses to the
"응답 (Response)" section in badge/assign.md: enumerate status codes 400, 401,
403, 404, and 409 with brief meanings (e.g., 400 Bad Request — empty/invalid
member IDs, 401 Unauthorized — missing/invalid JWT, 403 Forbidden — insufficient
permissions, 404 Not Found — badge or member IDs do not exist, 409 Conflict —
members already have the badge), and include at least one example JSON error
payload for each case similar to the existing success example so consumers can
see code/message/data fields for error responses.
Comment on lines
+42
to
+49
| **응답 예시** | ||
| ```json | ||
| { | ||
| "code": 201, | ||
| "message": "요청이 성공적으로 처리되었습니다.", | ||
| "data": null | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Response example shows null instead of assignment result.
The response should indicate which members were successfully assigned the badge, or at least a count. Currently showing "data": null provides no feedback on the operation outcome.
💡 Suggested response example
**응답 예시**
```json
{
"code": 201,
"message": "요청이 성공적으로 처리되었습니다.",
- "data": null
+ "data": {
+ "assignedCount": 2,
+ "memberIds": [101, 102]
+ }
}🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@badge/assign.md` around lines 42 - 49, Update the response example in
badge/assign.md so the "data" field returns assignment results instead of null:
populate "data" with at least an assignedCount and optionally a memberIds array
(e.g., "assignedCount": <n>, "memberIds": [<ids>]) to reflect which members were
successfully assigned the badge; ensure the example JSON under the "응답 예시"
section replaces "data": null with this structured result so consumers can see
operation outcome.
Comment on lines
+1
to
+44
| ## 배지 삭제 | ||
|
|
||
| ### 개요 | ||
| 배지 삭제 | ||
|
|
||
| ### 엔드포인트 | ||
| `DELETE /v1/admin/badges/{badgeId}` | ||
|
|
||
| ### 인증 | ||
| - **인증 필요 여부:** JWT 인증 필요 | ||
| - **권한:** 관리자만 접근 가능 (MANAGER 이상) | ||
|
|
||
| > 요청 헤더(Header)에 아래와 같이 Authorization 필드를 포함해야 합니다. | ||
| > `Authorization: Bearer {JWT_TOKEN}` | ||
|
|
||
| ### 요청 (Request) | ||
|
|
||
| **Headers** | ||
| | Key | Type | 설명 | 필수 | | ||
| |-----|------|------|------| | ||
| | Authorization | String | Bearer 토큰 | O | | ||
|
|
||
| **Path Parameters** | ||
| | Key | Type | 설명 | 필수 | | ||
| |-----|------|------|------| | ||
| | badgeId | Long | badgeId | O | | ||
|
|
||
| --- | ||
|
|
||
| ### 응답 (Response) | ||
|
|
||
| **성공** | ||
| | HTTP Status | 의미 | | ||
| |-------------|------| | ||
| | 200 OK | 요청 성공 | | ||
|
|
||
| **응답 예시** | ||
| ```json | ||
| { | ||
| "code": 200, | ||
| "message": "요청이 성공적으로 처리되었습니다.", | ||
| "data": null | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Missing critical business logic documentation.
The documentation doesn't explain:
- What happens to members who currently have this badge?
- Are there any constraints preventing deletion (e.g., if badge is assigned)?
- Is this a soft delete or hard delete?
These details are critical for API consumers to understand the impact of the deletion operation.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@badge/delete.md` around lines 1 - 44, Update the badge/delete.md
documentation for the DELETE /v1/admin/badges/{badgeId} endpoint to explicitly
state the business effects: describe whether deletion is soft or hard (e.g.,
soft-delete flag or physical removal), what happens to members who currently
have the badge (e.g., badge removed from member profiles, preserved history, or
left unchanged), list any constraints that prevent deletion (e.g., cannot delete
if badge is assigned, requires unassignment, or only deletable by MANAGER role),
and clarify how the response (the example with "data": null and 200 OK) should
be interpreted in each case; include these details under the "개요" or a new "영향 및
제약" section so API consumers can understand impact and preconditions for DELETE
/v1/admin/badges/{badgeId}.
Comment on lines
+30
to
+44
| ### 응답 (Response) | ||
|
|
||
| **성공** | ||
| | HTTP Status | 의미 | | ||
| |-------------|------| | ||
| | 200 OK | 요청 성공 | | ||
|
|
||
| **응답 예시** | ||
| ```json | ||
| { | ||
| "code": 200, | ||
| "message": "요청이 성공적으로 처리되었습니다.", | ||
| "data": null | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Missing error case documentation.
Document error scenarios such as:
- 401 Unauthorized: Missing or invalid JWT
- 403 Forbidden: Insufficient permissions (non-MANAGER)
- 404 Not Found: Badge ID does not exist
- 409 Conflict: Badge cannot be deleted (if constraints exist)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@badge/delete.md` around lines 30 - 44, The Response section in
badge/delete.md currently only documents the 200 success case; add documented
error responses for 401 Unauthorized (missing/invalid JWT), 403 Forbidden
(insufficient role/non-MANAGER), 404 Not Found (badge ID not found), and 409
Conflict (badge cannot be deleted due to constraints), each with a short
description and an example JSON body similar to the success example (code,
message, data), and include the corresponding HTTP status codes under the
response table so consumers can see both status and example payloads.
Comment on lines
+28
to
+34
| **Body (BadgeUpdateReqDTO)** | ||
| | Key | Type | 설명 | 필수 | | ||
| |-----|------|------|------| | ||
| | name | String | name | X | | ||
| | imageUrl | String | imageUrl | X | | ||
| | description | String | description | X | | ||
| | requirement | String | requirement | X | |
There was a problem hiding this comment.
Improve field descriptions beyond placeholder text.
The current descriptions simply repeat the field name (e.g., "name" → "name"), providing no useful information for API consumers. Each field should include:
- Purpose and business meaning
- Format constraints (e.g., max length, allowed characters)
- Examples or patterns
- Any validation rules
📝 Example of improved descriptions
**Body (BadgeUpdateReqDTO)**
| Key | Type | 설명 | 필수 |
|-----|------|------|------|
-| name | String | name | X |
-| imageUrl | String | imageUrl | X |
-| description | String | description | X |
-| requirement | String | requirement | X |
+| name | String | 배지 이름 (최대 50자) | X |
+| imageUrl | String | 배지 이미지 URL (HTTPS 필수) | X |
+| description | String | 배지에 대한 설명 (최대 200자) | X |
+| requirement | String | 배지 획득 조건 설명 (최대 100자) | X |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| **Body (BadgeUpdateReqDTO)** | |
| | Key | Type | 설명 | 필수 | | |
| |-----|------|------|------| | |
| | name | String | name | X | | |
| | imageUrl | String | imageUrl | X | | |
| | description | String | description | X | | |
| | requirement | String | requirement | X | | |
| **Body (BadgeUpdateReqDTO)** | |
| | Key | Type | 설명 | 필수 | | |
| |-----|------|------|------| | |
| | name | String | 배지 이름 (최대 50자) | X | | |
| | imageUrl | String | 배지 이미지 URL (HTTPS 필수) | X | | |
| | description | String | 배지에 대한 설명 (최대 200자) | X | | |
| | requirement | String | 배지 획득 조건 설명 (최대 100자) | X | |
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 33-33: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@badge/update.md` around lines 28 - 34, The current BadgeUpdateReqDTO field
descriptions are placeholders; update the docs for BadgeUpdateReqDTO to replace
each field's description with clear purpose, format constraints, examples, and
validation rules: for name describe business meaning (display/title for badge),
max length (e.g., 50 chars), allowed characters (letters, digits, spaces,
hyphens), and example; for imageUrl state it must be a valid HTTPS URL, max
length (e.g., 2048), allowed formats (png,jpg,svg) and example; for description
explain usage (short human-readable summary), max length (e.g., 250), prohibited
content rules and example; for requirement explain the badge unlock criteria
(plain text or markdown), max length (e.g., 1000), any structured pattern or
keys if required and example; include explicit validation rules
(required/optional, trimming, uniqueness constraints) for each field and add
representative examples for API consumers.
Comment on lines
+38
to
+52
| ### 응답 (Response) | ||
|
|
||
| **성공** | ||
| | HTTP Status | 의미 | | ||
| |-------------|------| | ||
| | 200 OK | 요청 성공 | | ||
|
|
||
| **응답 예시** | ||
| ```json | ||
| { | ||
| "code": 200, | ||
| "message": "요청이 성공적으로 처리되었습니다.", | ||
| "data": null | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Missing error case documentation.
The documentation lacks error scenarios that API consumers need to handle. Consider documenting:
- 400 Bad Request: Invalid input validation
- 401 Unauthorized: Missing or invalid JWT
- 403 Forbidden: Insufficient permissions (non-MANAGER)
- 404 Not Found: Badge ID does not exist
- 422 Unprocessable Entity: At least one field must be provided for update
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 38-38: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@badge/update.md` around lines 38 - 52, Add missing error-case documentation
under the "응답 (Response)" section in badge/update.md: list and describe the HTTP
error responses (400 Bad Request for invalid input, 401 Unauthorized for
missing/invalid JWT, 403 Forbidden for non-MANAGER permission, 404 Not Found for
nonexistent badge ID, 422 Unprocessable Entity when no update fields provided)
and include an example JSON response for each status similar to the existing
success example to guide API consumers.
Comment on lines
+45
to
+52
| **응답 예시** | ||
| ```json | ||
| { | ||
| "code": 200, | ||
| "message": "요청이 성공적으로 처리되었습니다.", | ||
| "data": null | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Response example shows null data instead of actual update result.
For a PATCH endpoint, the response should typically return the updated badge object or at least confirmation details, not null. This makes it difficult for API consumers to verify the update was applied correctly.
💡 Suggested response example
**응답 예시**
```json
{
"code": 200,
"message": "요청이 성공적으로 처리되었습니다.",
- "data": null
+ "data": {
+ "badgeId": 1,
+ "name": "업데이트된 배지명",
+ "imageUrl": "https://example.com/badge.png",
+ "description": "업데이트된 설명",
+ "requirement": "업데이트된 조건"
+ }
}🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@badge/update.md` around lines 45 - 52, The example response for the PATCH
badge endpoint currently returns "data": null; update the example in
badge/update.md to return the updated badge object instead (include fields such
as badgeId, name, imageUrl, description, requirement) so consumers can verify
the update—replace the null data with a JSON object showing the updated badge
values as in the suggested example.
| @@ -95,6 +95,14 @@ | |||
|
|
|||
| * [뱃지 부여](badge/create.md) | |||
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Spelling inconsistency: "뱃지" vs "배지".
Line 96 uses "뱃지" while lines 98-105 use "배지". The standard Korean spelling for "badge" is "배지" (without ㅅ). Consider updating line 96 and the section header (line 94) to use the consistent spelling "배지" throughout.
📝 Proposed fix for spelling consistency
-* [뱃지 부여](badge/create.md)
+* [배지 부여](badge/create.md)Also consider updating the section header:
-## Badge (활동뱃지) <a href="#badge" id="badge"></a>
+## Badge (활동배지) <a href="#badge" id="badge"></a>Also applies to: 98-105
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@SUMMARY.md` at line 96, Fix the Korean spelling inconsistency by replacing
"뱃지" with the standard "배지" everywhere — specifically update the bullet text "*
[뱃지 부여](badge/create.md)" and the corresponding section header and occurrences
in the badge section (the lines that currently use "뱃지") so all instances read
"배지" (e.g., change "뱃지 부여" to "배지 부여" and any headings or list items in the
badge section to use "배지").
Duplicate entries for badge assignment.
Lines 96 and 103 both represent badge assignment functionality but link to different files:
- Line 96: "뱃지 부여" →
badge/create.md - Line 103: "배지 부여" →
badge/assign.md
This creates confusion for users about which endpoint to use. Additionally, the file naming suggests that create.md should be for creating a new badge entity (not assignment), while assign.md correctly represents badge assignment.
Please clarify the distinction between these two entries or consolidate them into a single entry.
Also applies to: 103-103
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@SUMMARY.md` at line 96, There are duplicate SUMMARY entries titled "뱃지 부여"
pointing to badge/create.md and "배지 부여" pointing to badge/assign.md causing
confusion; update SUMMARY.md to either consolidate into one entry that links to
badge/assign.md (if that document is the assignment endpoint) and change the
badge/create.md heading/link to "뱃지 생성" (or similar) to reflect badge entity
creation, or clearly rename/update both link texts so one reads "뱃지 생성" ->
badge/create.md and the other reads "뱃지 부여" -> badge/assign.md to clarify their
distinct purposes.
|
|
||
| * [뱃지 부여](badge/create.md) | ||
| * [내 뱃지 조회](badge/my-list.md) | ||
| * [배지 생성](badge/post-create.md) |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
File naming convention inconsistency.
The file post-create.md includes an HTTP method prefix (post-), while other files in the same section (delete.md, update.md, assign.md, remove.md) and throughout the documentation don't follow this convention. For consistency, consider renaming to create.md or applying the HTTP method prefix consistently across all endpoints.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@SUMMARY.md` at line 98, The summary references an inconsistent file name
"post-create.md" which uses an HTTP method prefix while sibling files use verbs
like "delete.md", "update.md", "assign.md", "remove.md"; rename "post-create.md"
to "create.md" and update any links in SUMMARY.md and other docs that reference
"post-create.md" to the new name (ensure the TOC entry "* [배지
생성](badge/create.md)" replaces the current link), or alternatively apply the
same "post-" prefix to all badge endpoint files—pick one convention and make
filenames and all cross-references consistent across the badge docs.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
자동 동기화 알림
SURF-BE
dev브랜치의 컨트롤러/DTO 변경사항이 감지되어 API 문서를 자동 동기화합니다.새로 생성된 문서
badge/assign.md
badge/delete.md
badge/get-badge-list.md
badge/get-member-badges.md
badge/get-members.md
badge/post-create.md
badge/remove.md
badge/update.md
주의사항
Summary by CodeRabbit