fix(api): show structured add example in /docs for /product/add

[shinetata]

Description

The interactive API docs (/docs) for POST /product/add show "messages": "string" in the request example, which conflicts with the official docs (a structured message list) and misleads users into sending plain text.

Root cause: APIADDRequest.messages is typed str | MessageList | RawMessageList. Pydantic v2 renders this as an anyOf, and Swagger UI builds the "Example Value" from the first branch (str), so it displays "string". Fields like chat_history (a plain list) render correctly, which confirms the cause.

Fix: add a model-level json_schema_extra example to APIADDRequest so /docs shows a copy-paste-ready payload with a structured messages list plus the common fields. This is a schema-only change — field types, validation, the deprecated-field validator and runtime behaviour are all unchanged, so the core add pipeline is unaffected.

Related Issue (Required): Fixes #1505

Type of change

• Bug fix (non-breaking change which fixes an issue)

How Has This Been Tested?

• Unit Test

Added tests/api/test_product_models.py, which asserts the generated OpenAPI schema exposes a model-level example whose messages is a non-empty structured list (not a bare string) and covers the core add fields.

$ uv run --with pytest pytest tests/api/test_product_models.py -v
tests/api/test_product_models.py::test_add_request_exposes_model_level_example PASSED
tests/api/test_product_models.py::test_add_request_example_messages_is_structured_list PASSED
tests/api/test_product_models.py::test_add_request_example_covers_core_fields PASSED
3 passed, 2 warnings in 25.30s

Also ran ruff format --check and ruff check on the changed files — all passed.

Checklist

• I have performed a self-review of my own code | 我已自行检查了自己的代码
• I have commented my code in hard-to-understand areas | 我已在难以理解的地方对代码进行了注释
• I have added tests that prove my fix is effective or that my feature works | 我已添加测试以证明我的修复有效或功能正常
• I have created related documentation issue/PR in MemOS-Docs (if applicable) — repo docs already list messages as list/str; no docs change needed
• I have linked the issue to this PR (if applicable) | 我已将 issue 链接到此 PR
• I have mentioned the person who will review this PR

Reviewer Checklist

• closes fix: 接口文档内容不一致 #1505
• Made sure Checks passed
• Tests have been provided

Made with Cursor

[Memtensor-AI]

🤖 Open Code Review

Target: PR #2112
Task: 58847ff0280a1830
Base: dev-v2.0.24
Head: fix/add-request-openapi-example

🔍 OpenCodeReview found 2 issue(s) in this PR.

⚠️ 1 warning(s) occurred during review.

---

1. tests/api/test_product_models.py (L25-L27)

Direct subscript schema["example"] will raise a KeyError (not a readable AssertionError) if the key is absent, since this test does not first assert the key exists. Each test should be self-contained. Guard with an assertion before subscripting, or use .get() with an explicit assertion.

Suggested fix:

schema = APIADDRequest.model_json_schema()
assert "example" in schema, "APIADDRequest should define a model-level example"
example = schema["example"]

💡 Suggested Change

Before:

    example = APIADDRequest.model_json_schema()["example"]

    messages = example.get("messages")

After:

    schema = APIADDRequest.model_json_schema()
    assert "example" in schema, "APIADDRequest should define a model-level example"
    example = schema["example"]

    messages = example.get("messages")

---

2. tests/api/test_product_models.py (L38-L40)

Same issue: direct subscript ["example"] raises a KeyError instead of a clear AssertionError when the key is missing. This test should independently guard against an absent example key to be self-contained.

Suggested fix:

schema = APIADDRequest.model_json_schema()
assert "example" in schema, "APIADDRequest should define a model-level example"
example = schema["example"]

💡 Suggested Change

Before:

    example = APIADDRequest.model_json_schema()["example"]

    assert "user_id" in example

After:

    schema = APIADDRequest.model_json_schema()
    assert "example" in schema, "APIADDRequest should define a model-level example"
    example = schema["example"]

    assert "user_id" in example

---

🧹 Filtered 10 low-confidence OCR finding(s) before posting/fix-loop (duplicate: 10).

Generated by cloud-assistant via Open Code Review.