docs: API 문서 자동 동기화 — 2026-05-04 - #6
GOOHAESEUNG wants to merge 1 commit into
Conversation
📝 WalkthroughWalkthroughTwo new API endpoint documentations were added—one for member terms acceptance and one for badge single retrieval—with corresponding table-of-contents entries added to ChangesTerms Acceptance Documentation
Badge Single Retrieval Documentation
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 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. Review rate limit: 0/1 reviews remaining, refill in 60 minutes.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: 5
🤖 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/get-badge-single.md`:
- Around line 3-53: The API doc for GET /v1/admin/badges/{badgeId} is missing
business-logic rules and representative error responses; update the document to
include rule-level behavior for the endpoint (e.g., authorization requirement:
JWT Bearer and role MANAGER, visibility rules, whether soft-deleted badges are
returned, how IDs are validated, and any field derivation or formatting for
BadgeDetailResDTO fields like badgeId, name, imageUrl, description,
requirement), and add example failure responses with HTTP statuses and JSON
bodies for common cases (401 Unauthorized when Authorization header
missing/invalid, 403 Forbidden when role < MANAGER, 404 Not Found when badgeId
does not exist, 400 Bad Request for invalid badgeId format, and 500 Internal
Server Error for unexpected failures), making sure to include sample response
payloads and brief descriptions for each case.
- Around line 37-52: The response example for BadgeDetailResDTO is inconsistent:
the schema lists fields (badgeId, name, imageUrl, description, requirement) but
the example shows "data": null; update the example in get-badge-single.md so
that "data" contains a BadgeDetailResDTO object with the listed fields (badgeId,
name, imageUrl, description, requirement) populated with realistic sample
values, or explicitly document that BadgeDetailResDTO may be nullable and show
both a populated example and a null-case example; ensure the DTO name
BadgeDetailResDTO and field names appear verbatim in the updated example.
- Around line 1-53: The markdown violates MD041/MD022/MD058/MD031; update the
document so it uses a single top-level heading (replace the initial "## 배지 단건
조회" with "# 배지 단건 조회" or add a proper top-level heading), ensure there is
exactly one blank line above and below each heading and tables (normalize
spacing around "### 개요", "### 엔드포인트", "### 인증", "### 요청 (Request)", "### 응답
(Response)"), add a blank line before and after fenced code blocks and tables,
and fix the JSON example fence to include the language marker (```json) and a
matching closing fence so the example block is lint-clean. Ensure all heading
levels and blank lines around the table rows and code fences conform to
markdownlint rules.
In `@member/agree-terms.md`:
- Around line 3-39: The API doc for PATCH /v1/user/members/terms/agree is
incomplete: update member/agree-terms.md to fully describe behavior and error
semantics for the endpoint (/v1/user/members/terms/agree), including: the
request preconditions (JWT Authorization required and MEMBER+ role), the
business outcomes (what happens when a user successfully agrees — e.g., set
termsAccepted=true, record acceptedAt timestamp), idempotency (if 이미 동의한 경우
return 200 with a clear message or 409 depending on policy), all relevant error
responses (401 for missing/invalid token, 403 for insufficient role, 400 for
validation errors, 409 for conflict if you choose, 500 for server errors) with
example JSON payloads and specific code/message fields, and the exact
shape/meaning of the response data (e.g., data: { userId: string, termsVersion:
string, acceptedAt: ISO8601|null } or null). Ensure each example shows headers,
request body (if any), and corresponding success and error responses.
- Around line 1-39: Change the top-level heading from "## 약관 동의" to a single H1
("# 약관 동의") and ensure all headings (e.g., "### 개요", "### 엔드포인트", "### 인증", "###
요청 (Request)", "### 응답 (Response)") have a single blank line before and after
them; also add a blank line before and after the headers table and the fenced
JSON example (the ```json block) so the table and code fence are each surrounded
by blank lines to satisfy MD041/MD022/MD031/MD058.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 663e43ca-e673-428c-bb06-a19c559d9f01
📒 Files selected for processing (3)
SUMMARY.mdbadge/get-badge-single.mdmember/agree-terms.md
| ## 배지 단건 조회 | ||
|
|
||
| ### 개요 | ||
| 배지 단건 조회 | ||
|
|
||
| ### 엔드포인트 | ||
| `GET /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 | 요청 성공 | | ||
|
|
||
| **Body (BadgeDetailResDTO)** | ||
| | Key | Type | 설명 | | ||
| |-----|------|------| | ||
| | badgeId | Long | badgeId | | ||
| | name | String | name | | ||
| | imageUrl | String | imageUrl | | ||
| | description | String | description | | ||
| | requirement | String | requirement | | ||
|
|
||
| **응답 예시** | ||
| ```json | ||
| { | ||
| "code": 200, | ||
| "message": "요청이 성공적으로 처리되었습니다.", | ||
| "data": null | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Fix markdownlint violations before merge.
This file currently violates MD041/MD022/MD058/MD031 (top-level heading, blank lines around headings/tables/fences). Please normalize formatting to keep docs lint-clean.
Suggested formatting cleanup
-## 배지 단건 조회
+# 배지 단건 조회
### 개요
+
배지 단건 조회
### 엔드포인트
+
`GET /v1/admin/badges/{badgeId}`
### 인증
+
- **인증 필요 여부:** JWT 인증 필요
- **권한:** 관리자만 접근 가능 (MANAGER 이상)
@@
**Headers**
+
| Key | Type | 설명 | 필수 |
|-----|------|------|------|
| Authorization | String | Bearer 토큰 | O |
@@
**Path Parameters**
+
| Key | Type | 설명 | 필수 |
|-----|------|------|------|
| badgeId | Long | badgeId | O |
@@
**성공**
+
| HTTP Status | 의미 |
|-------------|------|
| 200 OK | 요청 성공 |
@@
**Body (BadgeDetailResDTO)**
+
| Key | Type | 설명 |
|-----|------|------|
| badgeId | Long | badgeId |
@@
**응답 예시**
+
```json
{
"code": 200,
"message": "요청이 성공적으로 처리되었습니다.",
"data": null
}</details>
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.22.1)</summary>
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
---
[warning] 3-3: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
---
[warning] 6-6: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
---
[warning] 9-9: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
---
[warning] 19-19: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
---
[warning] 24-24: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
---
[warning] 33-33: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
---
[warning] 38-38: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
---
[warning] 47-47: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against the current code and only fix it if needed.
In @badge/get-badge-single.md around lines 1 - 53, The markdown violates
MD041/MD022/MD058/MD031; update the document so it uses a single top-level
heading (replace the initial "## 배지 단건 조회" with "# 배지 단건 조회" or add a proper
top-level heading), ensure there is exactly one blank line above and below each
heading and tables (normalize spacing around "### 개요", "### 엔드포인트", "### 인증",
"### 요청 (Request)", "### 응답 (Response)"), add a blank line before and after
fenced code blocks and tables, and fix the JSON example fence to include the
language marker (```json) and a matching closing fence so the example block is
lint-clean. Ensure all heading levels and blank lines around the table rows and
code fences conform to markdownlint rules.
</details>
<!-- fingerprinting:phantom:triton:hawk:eeb67cb1-dc2a-4f7a-858b-269abbab9bc7 -->
<!-- d98c2f50 -->
<!-- This is an auto-generated comment by CodeRabbit -->
| ### 개요 | ||
| 배지 단건 조회 | ||
|
|
||
| ### 엔드포인트 | ||
| `GET /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 | 요청 성공 | | ||
|
|
||
| **Body (BadgeDetailResDTO)** | ||
| | Key | Type | 설명 | | ||
| |-----|------|------| | ||
| | badgeId | Long | badgeId | | ||
| | name | String | name | | ||
| | imageUrl | String | imageUrl | | ||
| | description | String | description | | ||
| | requirement | String | requirement | | ||
|
|
||
| **응답 예시** | ||
| ```json | ||
| { | ||
| "code": 200, | ||
| "message": "요청이 성공적으로 처리되었습니다.", | ||
| "data": null | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Required completion sections are still missing in this skeleton.
Before merge, this doc still needs business logic 설명 and error cases (PR objective checklist). Please add at least rule-level behavior and representative 실패 응답(권한 없음/대상 없음 등).
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 3-3: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 6-6: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 9-9: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 19-19: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
[warning] 24-24: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
[warning] 33-33: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
[warning] 38-38: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
[warning] 47-47: 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/get-badge-single.md` around lines 3 - 53, The API doc for GET
/v1/admin/badges/{badgeId} is missing business-logic rules and representative
error responses; update the document to include rule-level behavior for the
endpoint (e.g., authorization requirement: JWT Bearer and role MANAGER,
visibility rules, whether soft-deleted badges are returned, how IDs are
validated, and any field derivation or formatting for BadgeDetailResDTO fields
like badgeId, name, imageUrl, description, requirement), and add example failure
responses with HTTP statuses and JSON bodies for common cases (401 Unauthorized
when Authorization header missing/invalid, 403 Forbidden when role < MANAGER,
404 Not Found when badgeId does not exist, 400 Bad Request for invalid badgeId
format, and 500 Internal Server Error for unexpected failures), making sure to
include sample response payloads and brief descriptions for each case.
| **Body (BadgeDetailResDTO)** | ||
| | Key | Type | 설명 | | ||
| |-----|------|------| | ||
| | badgeId | Long | badgeId | | ||
| | name | String | name | | ||
| | imageUrl | String | imageUrl | | ||
| | description | String | description | | ||
| | requirement | String | requirement | | ||
|
|
||
| **응답 예시** | ||
| ```json | ||
| { | ||
| "code": 200, | ||
| "message": "요청이 성공적으로 처리되었습니다.", | ||
| "data": null | ||
| } |
There was a problem hiding this comment.
Response schema and example are inconsistent.
Body (BadgeDetailResDTO) lists detailed fields, but the example returns "data": null. Please align the example with the documented DTO (or explicitly document nullable behavior/조건).
Suggested example alignment
{
"code": 200,
"message": "요청이 성공적으로 처리되었습니다.",
- "data": null
+ "data": {
+ "badgeId": 1,
+ "name": "string",
+ "imageUrl": "https://example.com/badge.png",
+ "description": "string",
+ "requirement": "string"
+ }
}🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 38-38: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
[warning] 47-47: 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/get-badge-single.md` around lines 37 - 52, The response example for
BadgeDetailResDTO is inconsistent: the schema lists fields (badgeId, name,
imageUrl, description, requirement) but the example shows "data": null; update
the example in get-badge-single.md so that "data" contains a BadgeDetailResDTO
object with the listed fields (badgeId, name, imageUrl, description,
requirement) populated with realistic sample values, or explicitly document that
BadgeDetailResDTO may be nullable and show both a populated example and a
null-case example; ensure the DTO name BadgeDetailResDTO and field names appear
verbatim in the updated example.
| ## 약관 동의 | ||
|
|
||
| ### 개요 | ||
| 약관 동의 | ||
|
|
||
| ### 엔드포인트 | ||
| `PATCH /v1/user/members/terms/agree` | ||
|
|
||
| ### 인증 | ||
| - **인증 필요 여부:** JWT 인증 필요 | ||
| - **권한:** 일반 사용자 접근 가능 (MEMBER 이상) | ||
|
|
||
| > 요청 헤더(Header)에 아래와 같이 Authorization 필드를 포함해야 합니다. | ||
| > `Authorization: Bearer {JWT_TOKEN}` | ||
|
|
||
| ### 요청 (Request) | ||
|
|
||
| **Headers** | ||
| | Key | Type | 설명 | 필수 | | ||
| |-----|------|------|------| | ||
| | Authorization | String | Bearer 토큰 | O | | ||
|
|
||
| --- | ||
|
|
||
| ### 응답 (Response) | ||
|
|
||
| **성공** | ||
| | HTTP Status | 의미 | | ||
| |-------------|------| | ||
| | 200 OK | 요청 성공 | | ||
|
|
||
| **응답 예시** | ||
| ```json | ||
| { | ||
| "code": 200, | ||
| "message": "요청이 성공적으로 처리되었습니다.", | ||
| "data": null | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Resolve markdownlint warnings in this file.
The file has MD041/MD022/MD058/MD031 issues (top-level heading + blank-line spacing around headings/tables/fences). Please fix to keep docs CI stable and consistent.
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
[warning] 3-3: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 6-6: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 9-9: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 19-19: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
[warning] 28-28: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
[warning] 33-33: 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 `@member/agree-terms.md` around lines 1 - 39, Change the top-level heading from
"## 약관 동의" to a single H1 ("# 약관 동의") and ensure all headings (e.g., "### 개요",
"### 엔드포인트", "### 인증", "### 요청 (Request)", "### 응답 (Response)") have a single
blank line before and after them; also add a blank line before and after the
headers table and the fenced JSON example (the ```json block) so the table and
code fence are each surrounded by blank lines to satisfy
MD041/MD022/MD031/MD058.
| ### 개요 | ||
| 약관 동의 | ||
|
|
||
| ### 엔드포인트 | ||
| `PATCH /v1/user/members/terms/agree` | ||
|
|
||
| ### 인증 | ||
| - **인증 필요 여부:** JWT 인증 필요 | ||
| - **권한:** 일반 사용자 접근 가능 (MEMBER 이상) | ||
|
|
||
| > 요청 헤더(Header)에 아래와 같이 Authorization 필드를 포함해야 합니다. | ||
| > `Authorization: Bearer {JWT_TOKEN}` | ||
|
|
||
| ### 요청 (Request) | ||
|
|
||
| **Headers** | ||
| | Key | Type | 설명 | 필수 | | ||
| |-----|------|------|------| | ||
| | Authorization | String | Bearer 토큰 | O | | ||
|
|
||
| --- | ||
|
|
||
| ### 응답 (Response) | ||
|
|
||
| **성공** | ||
| | HTTP Status | 의미 | | ||
| |-------------|------| | ||
| | 200 OK | 요청 성공 | | ||
|
|
||
| **응답 예시** | ||
| ```json | ||
| { | ||
| "code": 200, | ||
| "message": "요청이 성공적으로 처리되었습니다.", | ||
| "data": null | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Document behavior and error semantics for this PATCH endpoint.
This endpoint doc is still skeletal: business logic and error cases are missing, and request/response contract detail is too thin for integration (e.g., 이미 동의한 경우 처리, 권한/인증 실패, 응답 data 구조/의미). Please complete these before merge per PR objective.
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 3-3: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 6-6: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 9-9: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 19-19: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
[warning] 28-28: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
[warning] 33-33: 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 `@member/agree-terms.md` around lines 3 - 39, The API doc for PATCH
/v1/user/members/terms/agree is incomplete: update member/agree-terms.md to
fully describe behavior and error semantics for the endpoint
(/v1/user/members/terms/agree), including: the request preconditions (JWT
Authorization required and MEMBER+ role), the business outcomes (what happens
when a user successfully agrees — e.g., set termsAccepted=true, record
acceptedAt timestamp), idempotency (if 이미 동의한 경우 return 200 with a clear message
or 409 depending on policy), all relevant error responses (401 for
missing/invalid token, 403 for insufficient role, 400 for validation errors, 409
for conflict if you choose, 500 for server errors) with example JSON payloads
and specific code/message fields, and the exact shape/meaning of the response
data (e.g., data: { userId: string, termsVersion: string, acceptedAt:
ISO8601|null } or null). Ensure each example shows headers, request body (if
any), and corresponding success and error responses.
1 participant
자동 동기화 알림
SURF-BE
dev브랜치의 컨트롤러/DTO 변경사항이 감지되어 API 문서를 자동 동기화합니다.새로 생성된 문서
badge/get-badge-single.md
member/agree-terms.md
주의사항
Summary by CodeRabbit
New Features
Documentation