🎨 Palette: Pydantic 스키마에 OpenAPI 예제 추가하여 DX 개선

[seonghobae]

• 💡 What: OpenAPI 스키마 (PageNode, ParseQuality, HealthResponse 등) 필드에 json_schema_extra={"example": ...}를 추가했습니다.
• 🎯 Why: 프론트엔드가 없는 백엔드 API 서비스이므로, 클라이언트 개발자가 Swagger UI를 통해 응답 모델 형태를 즉시 이해할 수 있도록 개발자 경험(DX)을 향상시켰습니다.
• 📸 Before/After: 예제가 없던 주요 필드들에 명시적인 예제가 추가되어 문서 가독성이 향상되었습니다.
• ♿ Accessibility/DX: OpenAPI 문서의 직관성과 가독성이 높아져 전반적인 API 사용성(DX)이 개선되었습니다.

---

PR created automatically by Jules for task 14380393862990811954 started by @seonghobae

[google-labs-jules]

👋 Jules, reporting for duty! I'm here to lend a hand with this pull request.

When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down.

I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job!

For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with @jules. You can find this option in the Pull Request section of your global Jules UI settings. You can always switch back!

New to Jules? Learn more at jules.google/docs.

---

For security, I will only act on instructions from the user who triggered this task.

[coderabbitai]

Warning

Review limit reached

@seonghobae, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 21 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 5faa7cde-2f84-42b0-99e3-c892fdcd08e2

📥 Commits

Reviewing files that changed from the base of the PR and between 04491c0 and ce728a5.

⛔ Files ignored due to path filters (1)

• uv.lock is excluded by !**/*.lock

📒 Files selected for processing (4)

• .jules/palette.md
• .trivyignore
• patch_palette.py
• src/newsdom_api/schemas.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch develop-14380393862990811954

---

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

This PR improves the API’s self-documentation by adding explicit OpenAPI examples to key Pydantic response schemas, helping clients understand response shapes directly from Swagger UI.

Changes:

• Added json_schema_extra={"example": ...} examples to several schema fields (ImageNode, ArticleNode, PageNode, ParseQuality, HealthResponse).
• Updated .jules/palette.md with a new learning/action entry related to schema examples.
• Added patch_palette.py (a small script that edits .jules/palette.md).

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File	Description
src/newsdom_api/schemas.py	Adds per-field OpenAPI examples to improve generated schema documentation (with some formatting consistency issues noted).
patch_palette.py	Introduces a repo script that edits .jules/palette.md by truncating lines (likely an unintended/temporary artifact).
.jules/palette.md	Adds a Korean DX note, but currently retains a shell placeholder heading that should be cleaned up.

Comments suppressed due to low confidence (4)

src/newsdom_api/schemas.py:138

• This multiline Field() call is missing a trailing comma after json_schema_extra, which is inconsistent with the rest of this file’s schema declarations and can lead to formatter churn. Add the trailing comma.

    ads: List[str] = Field(
        default_factory=list,
        description="Advertisement text blocks extracted from this page.",
        json_schema_extra={"example": ["Special offer: 50% off!"]}
    )

src/newsdom_api/schemas.py:143

• This multiline Field() call is missing a trailing comma after json_schema_extra, which is inconsistent with nearby Field() blocks and may cause avoidable formatting diffs. Add a trailing comma.

    headers: List[str] = Field(
        default_factory=list,
        description="Header text blocks extracted from this page.",
        json_schema_extra={"example": ["Top News Section"]}
    )

src/newsdom_api/schemas.py:148

• This multiline Field() call is missing a trailing comma after json_schema_extra, which is inconsistent with the rest of the file and can trigger formatter churn. Add a trailing comma.

    footers: List[str] = Field(
        default_factory=list,
        description="Footer text blocks extracted from this page.",
        json_schema_extra={"example": ["Page 1 of 10"]}
    )

src/newsdom_api/schemas.py:153

• This multiline Field() call is missing a trailing comma after json_schema_extra, which is inconsistent with the surrounding schema formatting and may cause avoidable reformatting diffs. Add a trailing comma.

    page_numbers: List[str] = Field(
        default_factory=list,
        description="Visible page-number text blocks extracted from this page.",
        json_schema_extra={"example": ["1"]}
    )

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 5 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (8)

src/newsdom_api/schemas.py:98

• This Field(...) block is missing the trailing comma after json_schema_extra, which is inconsistent with the surrounding schema definitions and can cause formatter churn / line-wrapping differences.

    body_blocks: List[str] = Field(
        default_factory=list,
        description="Ordered text blocks that make up the article body.",
        json_schema_extra={"example": ["First paragraph text.", "Second paragraph text."]}
    )

src/newsdom_api/schemas.py:143

• This Field(...) block is missing the trailing comma after json_schema_extra, which is inconsistent with the rest of the file and can trigger formatter-only diffs later.

    headers: List[str] = Field(
        default_factory=list,
        description="Header text blocks extracted from this page.",
        json_schema_extra={"example": ["Top News Section"]}
    )

src/newsdom_api/schemas.py:148

• This Field(...) block is missing the trailing comma after json_schema_extra; adding it keeps the style consistent with other schema fields.

    footers: List[str] = Field(
        default_factory=list,
        description="Footer text blocks extracted from this page.",
        json_schema_extra={"example": ["Page 1 of 10"]}
    )

src/newsdom_api/schemas.py:153

• This Field(...) block is missing the trailing comma after json_schema_extra; adding it matches the surrounding formatting and avoids formatter churn.

    page_numbers: List[str] = Field(
        default_factory=list,
        description="Visible page-number text blocks extracted from this page.",
        json_schema_extra={"example": ["1"]}
    )

src/newsdom_api/schemas.py:161

• This Field(...) call is compressed onto a single long line, unlike the rest of the schema file; it is also likely to exceed the formatter's line-length limit. Please format it like the other multi-line Field(...) declarations.

    status: str = Field(
        default="success", description="Parsing operation status indicator.", json_schema_extra={"example": "success"}
    )

src/newsdom_api/schemas.py:164

• This Field(...) call is compressed onto a single long line, unlike the rest of the schema file; it is also likely to exceed the formatter's line-length limit. Please format it like the other multi-line Field(...) declarations.

    parser: str = Field(
        default="mineru", description="The underlying engine used to parse the PDF.", json_schema_extra={"example": "mineru"}
    )

.jules/palette.md:2

• This file now has two consecutive H2 headings, and the first one includes a shell-style $(date ...) placeholder rather than an actual date. This makes the palette entry ambiguous; consider collapsing to a single dated heading.

## $(date +%Y-%m-%d) - Enhance Developer UX with OpenAPI Schema Examples
## 2025-02-27 - OpenAPI 스키마 예제(DX)

patch_palette.py:6

• This script destructively truncates .jules/palette.md by blindly dropping the last 5 lines, and it is not referenced anywhere in the repository. It looks like a one-off local patch and is risky to keep in the codebase; please remove it from the PR (or move it to a documented, non-destructive maintenance tool if it is genuinely needed).

with open(".jules/palette.md", "r") as f:
    lines = f.readlines()
# Remove English version that I just added
new_lines = lines[:-5]
with open(".jules/palette.md", "w") as f:
    f.writelines(new_lines)