🎨 Palette: Enhance OpenAPI DX with Pydantic Schema Examples#266
🎨 Palette: Enhance OpenAPI DX with Pydantic Schema Examples#266seonghobae wants to merge 4 commits into
Conversation
Enhanced OpenAPI / Swagger UI documentation by injecting concrete `examples` into the `Field` declarations for core schema models (`BoundingBox`, `ImageNode`, `ArticleNode`, `PageNode`, `ParseQuality`, `ParseResponse`, `HealthResponse`). This acts as a direct Developer Experience (DX) micro-UX improvement for backend-only services, allowing API consumers to view and test realistic payload data natively in the generated OpenAPI specs.
|
👋 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 New to Jules? Learn more at jules.google/docs. For security, I will only act on instructions from the user who triggered this task. |
There was a problem hiding this comment.
Pull request overview
Note
Copilot couldn't run its full agentic review because no GitHub Actions runner was available. Make sure your repository has a runner available to run Copilot's review, or add a copilot-setup-steps.yml file specifying one with the runs-on attribute. See the docs for more details.
Adds concrete Pydantic v2 Field(..., examples=...) metadata to core API schemas to improve Swagger/OpenAPI documentation usability, plus a short internal “palette” note documenting the pattern.
Changes:
- Added field-level example values to multiple Pydantic models used in API responses/structures.
- Updated internal
.Jules/palette.mdwith guidance on usingField(..., examples=...)for DX improvements.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| src/newsdom_api/schemas.py | Adds examples metadata to schema fields to improve generated OpenAPI docs. |
| .Jules/palette.md | Documents the “Field examples” approach as an internal guideline. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| x0: float = Field( | ||
| ..., description="Leftmost X coordinate of the bounding box.", examples=[72.5] | ||
| ) | ||
| y0: float = Field( | ||
| ..., description="Topmost Y coordinate of the bounding box.", examples=[100.0] | ||
| ) |
…ility
Resolved OpenAPI/Swagger UI tooling compatibility issues flagged by CI review. Refactored the raw `examples` parameter to use the standard Pydantic V2 `json_schema_extra={"examples": [...]}` format across all schema models (`BoundingBox`, `ImageNode`, `ArticleNode`, `PageNode`, `ParseQuality`, `ParseResponse`, `HealthResponse`). Also updated `.Jules/palette.md` to properly document the required array syntax.
…ility
Refactored OpenAPI example declarations in Pydantic V2 models to use `json_schema_extra={"example": <value>}` instead of `{"examples": [...]}` to resolve rendering inconsistencies in OpenAPI 3.0.x and Swagger UI tools, as raised during CI code review. Also updated Palette guidelines to explicitly document the scalar `example` syntax.
…I compatibility
Resolved a CI feedback loop where previous PRs triggered Pydantic V2 `PydanticDeprecatedSince20` warnings for using `example=` directly, or encountered Swagger UI compatibility issues for using `json_schema_extra={"examples": [...]}`. Properly refactored `src/newsdom_api/schemas.py` to use `json_schema_extra={"example": ...}` and updated Palette documentation to match, passing all 321 tests with 0 warnings.
OpenCode Review Overview
Pull request overviewOpenCode reviewed the current-head evidence but found unresolved reviewer or review-agent threads before approval. Findings1. HIGH .github/workflows/opencode-review.yml:1 - Unresolved reviewer thread blocks automated approval
Review thread evidenceLatest unresolved reviewer thread evidence
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Pull request overview
OpenCode reviewed the current-head evidence but found unresolved reviewer or review-agent threads before approval.
Findings
1. HIGH .github/workflows/opencode-review.yml:1 - Unresolved reviewer thread blocks automated approval
- Problem: OpenCode reached an APPROVE control result, but the approval step found unresolved, non-outdated human or review-agent thread evidence on the current pull request.
- Root cause: Reviewer and review-agent feedback can arrive after bounded model evidence is prepared, so the approval step must re-query GitHub immediately before publishing an approval.
- Fix: Address or resolve the listed reviewer thread(s), then re-run OpenCode on the current head.
- Regression test: Keep the approval gate querying reviewThreads(first: 100) after model output and before create_pull_review APPROVE, including bot review agents other than OpenCode itself.
Review thread evidence
Latest unresolved reviewer thread evidence
src/newsdom_api/schemas.py line 22
-
Latest reviewer comment: @copilot-pull-request-reviewer at 2026-07-02T22:18:02Z
-
Comment URL: #266 (comment)
-
Comment excerpt: Using JSON Schema’s 'examples' keyword at the property level is not consistently rendered by all OpenAPI/Swagger tooling (especially if the app is still emitting OpenAPI 3.0.x). If the goal is to reliably populate Swagger UI’s “Example Value”, consider switching these to an 'example=' / 'json_schema_extra={"example": ...}' style that Swagger UI consumes more consistently, or explicitly ensure the service emits OpenAPI 3.1 where 'examples' is expected to be honored.
-
Result: REQUEST_CHANGES
-
Reason: unresolved reviewer or review-agent thread(s) were present before approval.
-
Head SHA:
301aef5d1beeea6fd48e585e186f3def8261f601 -
Workflow run: 28682329638
-
Workflow attempt: 1
Changed-File Evidence Map
flowchart LR
PR["PR changed files"] --> Evidence["OpenCode bounded evidence"]
Evidence --> S1["Changed file (2 files)"]
S1 --> I1["repository behavior"]
I1 --> R1["Review risk: Changed file (2 files)"]
R1 --> V1["required checks"]
What (구현 내용)
src/newsdom_api/schemas.py의 Pydantic V2 모델 선언부에 구체적인examples파라미터를 추가했습니다. 주요 변경 대상은BoundingBox,CaptionNode,ImageNode,ArticleNode,PageNode,ParseQuality,ParseResponse,HealthResponse등 코어 모델들입니다.Why (해결하는 문제)
프론트엔드 UI가 없는 백엔드 전용 API 서비스의 특성상, 개발자 경험(DX)이 곧 사용자 경험(UX)과 직결됩니다. 기존 OpenAPI(Swagger) 문서에서는 구체적인 예시 값이 제공되지 않아, API 연동 및 테스트를 진행하는 개발자가 페이로드 형식을 직관적으로 유추하기 어려웠습니다. 이번 패치를 통해 OpenAPI 명세서 자체에서 현실적인 예시를 제공하여 개발자의 문서 이해도 및 편의성을 극대화합니다.
Impact (성능/영향)
.Jules/palette.md파일에 Pydantic V2Field와examples를 활용한 UX 개선 방법론을 추가하여 조직적 학습에 기여했습니다.Measurement (측정/검증 방법)
uv run ruff format및uv run ruff check통과 확인.uv run pytest) 321개 테스트가 모두 성공함을 확인했습니다.PR created automatically by Jules for task 1305316119032306146 started by @seonghobae