Mintlify OpenAPI example not rendering nested objects - code context

mintlify-openapi-example-issue.py

"""
Issue: OpenAPI `example` field with nested objects not rendering correctly in Mintlify.

The nested `image_url` object renders as `{"type": "image_url"}` instead of the full structure
with the nested `image_url.url` field.

Expected in docs:
{
  "type": "image_url",
  "image_url": {
    "url": "https://..."
  }
}

Actual in docs:
{
  "type": "image_url"
}
"""

# This is the example we inject into the OpenAPI schema
CHAT_COMPLETIONS_SAMPLE = {
    "model": "n1-preview-2025-11",
    "temperature": 0.3,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Describe the screenshot and search for Yutori.",
                }
            ],
        },
        {
            "role": "observation",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://upload.wikimedia.org/wikipedia/commons/5/53/Google_homepage_%28as_of_January_2024%29.jpg"
                    },
                }
            ],
        },
    ],
}


def _ensure_chat_sample(post_operation: dict) -> None:
    """Set the default example payload Mintlify uses for the Playground for /chat/completions"""

    request_body = post_operation.setdefault("requestBody", {})
    content = request_body.setdefault("content", {})
    application_json = content.setdefault("application/json", {})
    application_json["example"] = CHAT_COMPLETIONS_SAMPLE


# This function is called when generating the OpenAPI schema:
def _apply_openapi_security(schema: dict) -> None:
    """Attach global API key security and override chat completions with bearer auth."""
    # ... security setup ...
    
    chat_path = schema.get("paths", {}).get("/v1/chat/completions")
    post_operation = chat_path.get("post")
    if isinstance(post_operation, dict):
        post_operation["security"] = [{"BearerAuth": []}]
        _ensure_chat_sample(post_operation)


# The resulting OpenAPI JSON has the correct example:
# paths./v1/chat/completions.post.requestBody.content.application/json.example
# 
# But Mintlify renders it incorrectly, dropping the nested image_url object.