From da5c430e608586bfc6b6d60d58d50af1a3f721c5 Mon Sep 17 00:00:00 2001 From: seonghobae <8172694+seonghobae@users.noreply.github.com> Date: Tue, 1 Sep 2026 21:24:22 +0000 Subject: [PATCH 1/5] =?UTF-8?q?feat(docs):=20Form=20=ED=95=84=EB=93=9C?= =?UTF-8?q?=EC=97=90=20OpenAPI=20example=20=EC=B6=94=EA=B0=80=ED=95=98?= =?UTF-8?q?=EC=97=AC=20DX=20=EA=B0=9C=EC=84=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .Jules/palette.md | 4 ++++ src/newsdom_api/main.py | 6 ++++-- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/.Jules/palette.md b/.Jules/palette.md index 6ac2f6ad..c825b305 100644 --- a/.Jules/palette.md +++ b/.Jules/palette.md @@ -29,3 +29,7 @@ ## 2026-07-07 - [Improve Swagger UX with Pydantic V2 Examples] **Learning:** Using json_schema_extra={'example': ...} instead of example=... in Pydantic V2 schemas ensures OpenAPI compatibility and prevents deprecation warnings, significantly improving Developer Experience (DX) for API consumers. **Action:** Apply json_schema_extra to Pydantic Field definitions to automatically generate rich, self-documenting OpenAPI schemas for headless APIs. + +## 2026-10-27 - FastAPI Form 의존성에 대한 OpenAPI 예제 제공 +**학습:** FastAPI의 `Form` 의존성을 사용할 때 OpenAPI(Swagger UI)에서 기본적으로 예제(example)가 제공되지 않아 API 소비자가 어떤 값을 입력해야 할지 혼란을 겪을 수 있습니다. 반면, `File` 업로드 필드에 예제를 추가하는 것은 Swagger UI에서 HTML 파일 선택기로 렌더링되므로 피해야 합니다. +**실행:** FastAPI의 라우트 의존성(`Form(...)`)에 `json_schema_extra={"example": "..."}`를 추가하여 Swagger UI에서 직관적인 페이로드 예제를 제공하고 개발자 경험(DX)을 향상시킵니다. diff --git a/src/newsdom_api/main.py b/src/newsdom_api/main.py index f61aafc2..3ad15414 100644 --- a/src/newsdom_api/main.py +++ b/src/newsdom_api/main.py @@ -208,7 +208,8 @@ async def parse( description=( "MinerU language family or compatibility alias (e.g. `ch`, " "`en`, `japan`, `korean`, `arabic`, `devanagari`)." - ) + ), + json_schema_extra={"example": "ch"}, ), ] = DEFAULT_LANGUAGE, mode: Annotated[ @@ -217,7 +218,8 @@ async def parse( description=( "MinerU parsing mode: `auto` (born-digital text PDFs skip forced " "OCR), `ocr` (force OCR), or `txt` (embedded text layer only)." - ) + ), + json_schema_extra={"example": "auto"}, ), ] = DEFAULT_MODE, ) -> ParseResponse: From 00bc4a9e26201998b4c4bd7773ad45a3324b2dfe Mon Sep 17 00:00:00 2001 From: seonghobae <8172694+seonghobae@users.noreply.github.com> Date: Wed, 2 Sep 2026 02:10:50 +0000 Subject: [PATCH 2/5] feat docs OpenAPI Form parameter example added for better DX From 7fdc4478e63df7b93a2563ac16e19eab526aef7e Mon Sep 17 00:00:00 2001 From: seonghobae <8172694+seonghobae@users.noreply.github.com> Date: Wed, 2 Sep 2026 10:40:25 +0000 Subject: [PATCH 3/5] Palette OpenAPI Form parameter example added for better DX From 71d394662bd6ed5c9ffa82fb8622e132e66aaeb6 Mon Sep 17 00:00:00 2001 From: seonghobae <8172694+seonghobae@users.noreply.github.com> Date: Wed, 2 Sep 2026 20:49:20 +0000 Subject: [PATCH 4/5] Palette OpenAPI Form parameter example added for better DX --- uv.lock | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/uv.lock b/uv.lock index a0d133b8..1ca380d4 100644 --- a/uv.lock +++ b/uv.lock @@ -303,7 +303,7 @@ name = "exceptiongroup" version = "1.3.1" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "typing-extensions" }, + { name = "typing-extensions", marker = "python_full_version < '3.11'" }, ] sdist = { url = "https://files.pythonhosted.org/packages/50/79/66800aadf48771f6b62f7eb014e352e5d06856655206165d775e675a02c9/exceptiongroup-1.3.1.tar.gz", hash = "sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219", size = 30371, upload-time = "2025-11-21T23:01:54.787Z" } wheels = [ @@ -929,14 +929,14 @@ wheels = [ [[package]] name = "pypdf" -version = "6.15.0" +version = "6.16.2" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "typing-extensions", marker = "python_full_version < '3.11'" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/17/17/ee75a92718ec7212de831e71454d702225aa5e474a805cce169806044453/pypdf-6.15.0.tar.gz", hash = "sha256:d39c4d955a76409284a905e2d65b40076d77ab76129e0faaeeb6612403ecfc79", size = 6993794, upload-time = "2026-08-06T13:06:49.929Z" } +sdist = { url = "https://files.pythonhosted.org/packages/44/66/54212e75406afd9f3e933d0dda23072f6aecc55c5a273077dc2e0b028b23/pypdf-6.16.2.tar.gz", hash = "sha256:595647f6191de6f402cfde1d0c455d6cbccbd509aac32b34783009c032de5d6e", size = 7008996, upload-time = "2026-08-23T13:50:07.135Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/af/72/ce3067ac31e214a66388159f8462ddb8c13dd00170f24d555a1f1ae8ee91/pypdf-6.15.0-py3-none-any.whl", hash = "sha256:14e001d6504822cb1ca9c7ed9a69bccb320f59b320730f55af804361abe4d5ee", size = 378123, upload-time = "2026-08-06T13:06:47.709Z" }, + { url = "https://files.pythonhosted.org/packages/13/f1/a2da3b55acd4ab737bf728c97edaaed5ec1d3c1236acb639dcdfa97e42c7/pypdf-6.16.2-py3-none-any.whl", hash = "sha256:c8b09a59399062fb45a1b8156c18a787a10a3dae03ac9674397a226712c94604", size = 385060, upload-time = "2026-08-23T13:50:05.349Z" }, ] [[package]] From fece4ecfa21eb1f33791360f9aa19bc0ece7e45c Mon Sep 17 00:00:00 2001 From: seonghobae <8172694+seonghobae@users.noreply.github.com> Date: Thu, 3 Sep 2026 10:28:18 +0000 Subject: [PATCH 5/5] Palette OpenAPI Form parameter example added for better DX