๐จ Palette: [๊ฐ๋ฐ์ ๊ฒฝํ ๊ฐ์ ] OpenAPI ์คํค๋ง์ ์์ ๋ฐ์ดํฐ ์ถ๊ฐ - #425
๐จ Palette: [๊ฐ๋ฐ์ ๊ฒฝํ ๊ฐ์ ] OpenAPI ์คํค๋ง์ ์์ ๋ฐ์ดํฐ ์ถ๊ฐ#425seonghobae wants to merge 2 commits into
Conversation
|
๐ 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
This PR improves the API documentation experience by adding explicit OpenAPI example values to schema fields, so Swagger UI shows more helpful sample payloads for consumers of the FastAPI service.
Changes:
- Added
json_schema_extra={"example": ...}toParseQualityfields (status,parser,warnings) to surface representative example values in generated OpenAPI. - Added
json_schema_extra={"example": ...}toHealthResponse.statusfor clearer health-check response examples. - Updated
.jules/palette.mdwith a short internal note about the OpenAPI schema example addition.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| src/newsdom_api/schemas.py | Adds OpenAPI example metadata to ParseQuality and HealthResponse fields for improved Swagger UI docs. |
| .jules/palette.md | Records an internal DX learning/action note related to adding schema examples. |
๐ก Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| # CVE-2026-61632 affects pymdown-extensions, but it cannot be fixed via uv upgrade due to missing patch | ||
| # Revisit by 2026-08-31 | ||
| CVE-2026-61632 |
| **Learning:** In a backend-only FastAPI project without frontend files, "UX" improvements naturally translate to Developer Experience (DX). Enhancing Pydantic schemas with `json_schema_extra={"example": ...}` rather than just using the `description` field or deprecated plural `examples` provides concrete, immediate value in the generated Swagger UI. Additionally, explicitly defining the ellipsis `...` for required fields is redundant and noisy in modern Pydantic V2 when no default is provided. | ||
| **Action:** When working on API schemas, proactively provide representative `json_schema_extra` examples to improve the consumer documentation experience, and omit the `...` default marker to keep schema declarations clean and idiomatic. | ||
|
|
||
| ## 2024-05-24 - OpenAPI ์คํค๋ง ์์ ์ถ๊ฐ |
๐ก What:
ParseQuality๋ฐHealthResponse๋ชจ๋ธ์ ํ๋์json_schema_extra={"example": ...}๋ฅผ ์ถ๊ฐํ์ฌ Swagger UI์์ ์ง๊ด์ ์ธ ์์ ๋ฅผ ๋ณผ ์ ์๋๋ก ๊ฐ์ ํ์ต๋๋ค.๐ฏ Why: ๋ฐฑ์๋ ์ ์ฉ ์ ํ๋ฆฌ์ผ์ด์ ์์ API ๋ฌธ์์ ๋ช ํ์ฑ์ ๊ฐ๋ฐ์ ๊ฒฝํ(DX)์ ๊ฒฐ์ ์ง๋ ํต์ฌ ์์์ ๋๋ค. ๊ตฌ์ฒด์ ์ธ ์์ ๊ฐ ์์ผ๋ฉด API ์ฐ๋ ๊ณผ์ ์ด ํจ์ฌ ์์ํด์ง๋๋ค.
๐ธ Before/After: ํด๋น ์์ (API ๋ฌธ์ UI ์์ ๋ณํ)
โฟ Accessibility: ํด๋น ์์ (UX/DX ๊ฐ์ )
PR created automatically by Jules for task 2088752217907062735 started by @seonghobae