Skip to content

fix: remove x-codeSamples so playground examples update live (#1015) (backport to release/1.17.0) #1018

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
RiskeyL merged 1 commit into from
Sep 1, 2026
Merged

fix: remove x-codeSamples so playground examples update live (#1015) (backport to release/1.17.0) #1018

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude/skills/dify-docs-api-reference/references/spec-conventions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,7 +163,7 @@ Same concept, same words, across all operations.

## x-codeSamples

Mintlify's playground auto-generates request samples from the schema; do not duplicate it. Add a hand-written `x-codeSamples` entry only where autogen fails: `multipart/form-data`, binary bodies, and SSE consumption. House format: `{"lang": "bash", "label": "cURL", "source": "curl --request …"}` with `{api_base_url}`, `{api_key}`, `{user}` placeholders. Code samples are identical across languages.
Do not add `x-codeSamples`; `lint_specs` flags any occurrence. A hand-written sample replaces Mintlify's generated snippets for the whole operation: the playground stops reflecting typed values, and readers lose every language tab but the one provided. Autogen handles all body types — `multipart/form-data` renders as `--form`, typed values appear live, and the pristine snippet draws from schema `default`s and the request-body example. A query parameter without a `default` is absent until typed; accept that gap rather than invent a `default` the API does not have. SSE consumption mechanics (curl's `--no-buffer`) live in the [SSE Streaming guide](/en/api-reference/guides/streaming).
Comment on lines 164 to +166

## Tag Naming

Expand Down
4 changes: 4 additions & 0 deletions en/api-reference/guides/streaming.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,10 @@ data: {"event": "workflow_started", "task_id": "c3800678-…", "workflow_run_id"
data: {"event": "node_finished", "task_id": "c3800678-…", "workflow_run_id": "fb47b2e6-…", "data": {…}}
```

<Tip>
When testing with curl, pass `-N` (`--no-buffer`) so events print as they arrive instead of after the run completes.
</Tip>

## Dispatch by Event Type

Which events arrive depends on the app type. See the event tables on [Send Chat Message](/en/api-reference/chat-messages/send-chat-message), [Run Workflow](/en/api-reference/workflow-runs/run-workflow), and [Send Completion Message](/en/api-reference/completion-messages/send-completion-message) for the contract.
Expand Down
100 changes: 9 additions & 91 deletions en/api-reference/openapi_service.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -421,14 +421,7 @@
"title": "Send Chat Message",
"sidebarTitle": "Send Chat Message"
}
},
"x-codeSamples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request POST \\\n --url 'https://{api_base_url}/chat-messages' \\\n --header 'Authorization: Bearer {api_key}' \\\n --header 'Content-Type: application/json' \\\n --no-buffer \\\n --data '{\"query\": \"What are the specs of the iPhone 13 Pro Max?\", \"inputs\": {}, \"response_mode\": \"streaming\", \"user\": \"{user}\"}'"
}
]
}
}
},
"/chat-messages/{task_id}/stop": {
Expand Down Expand Up @@ -629,13 +622,6 @@
}
}
},
"x-codeSamples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request GET \\\n --url 'https://{api_base_url}/messages/{message_id}/suggested?user={user}' \\\n --header 'Authorization: Bearer {api_key}'"
}
],
"x-mint": {
"href": "/en/api-reference/chat-messages/get-next-suggested-questions",
"metadata": {
Expand Down Expand Up @@ -793,14 +779,7 @@
"title": "Upload File",
"sidebarTitle": "Upload File"
}
},
"x-codeSamples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request POST \\\n --url 'https://{api_base_url}/files/upload' \\\n --header 'Authorization: Bearer {api_key}' \\\n --form 'file=@product-photo.png' \\\n --form 'user={user}'"
}
]
}
}
},
"/files/{file_id}/preview": {
Expand Down Expand Up @@ -1423,13 +1402,6 @@
}
}
},
"x-codeSamples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request GET \\\n --url 'https://{api_base_url}/messages?conversation_id={conversation_id}&user={user}' \\\n --header 'Authorization: Bearer {api_key}'"
}
],
"x-mint": {
"href": "/en/api-reference/conversations/list-conversation-messages",
"metadata": {
Expand Down Expand Up @@ -2069,14 +2041,7 @@
"title": "Convert Audio to Text",
"sidebarTitle": "Convert Audio to Text"
}
},
"x-codeSamples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request POST \\\n --url 'https://{api_base_url}/audio-to-text' \\\n --header 'Authorization: Bearer {api_key}' \\\n --form 'file=@meeting-question.mp3' \\\n --form 'user={user}'"
}
]
}
}
},
"/text-to-audio": {
Expand Down Expand Up @@ -3683,7 +3648,7 @@
"Workflow Runs"
],
"summary": "Stream Workflow Events",
"description": "**Available for**: Chatflow, Workflow apps.\n\nResume the Server-Sent Events stream for a workflow run after a pause or a dropped SSE connection. For runs that have already finished, the stream emits a single `workflow_finished` event and closes.\n\nTo check an in-progress run's node-level status and progress, call it with `include_state_snapshot=true`: the stream replays each already-executed node's status before streaming new events.",
"description": "**Available for**: Chatflow, Workflow apps.\n\nResume the [Server-Sent Events stream](/en/api-reference/guides/streaming) for a workflow run after a pause or a dropped SSE connection. For runs that have already finished, the stream emits a single `workflow_finished` event and closes.\n\nTo check an in-progress run's node-level status and progress, call it with `include_state_snapshot=true`: the stream replays each already-executed node's status before streaming new events.",
"operationId": "streamWorkflowEvents",
"parameters": [
{
Expand Down Expand Up @@ -3783,18 +3748,6 @@
}
}
},
"x-codeSamples": [
{
"lang": "bash",
"label": "Resume stream",
"source": "curl -N --request GET \\\n --url 'https://{api_base_url}/workflow/{workflow_run_id}/events?user={user}' \\\n --header 'Authorization: Bearer {api_key}'"
},
{
"lang": "bash",
"label": "With state snapshot",
"source": "curl -N --request GET \\\n --url 'https://{api_base_url}/workflow/{workflow_run_id}/events?user={user}&include_state_snapshot=true' \\\n --header 'Authorization: Bearer {api_key}'"
}
],
"x-mint": {
"href": "/en/api-reference/workflow-runs/stream-workflow-events",
"metadata": {
Expand Down Expand Up @@ -4021,14 +3974,7 @@
"title": "Run Workflow",
"sidebarTitle": "Run Workflow"
}
},
"x-codeSamples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl -N --request POST \\\n --url 'https://{api_base_url}/workflows/run' \\\n --header 'Authorization: Bearer {api_key}' \\\n --header 'Content-Type: application/json' \\\n --data '{\"inputs\": {\"query\": \"Summarize this text: The quick brown fox jumps over the lazy dog.\"}, \"response_mode\": \"streaming\", \"user\": \"{user}\"}'"
}
]
}
}
},
"/workflows/{workflow_id}/run": {
Expand Down Expand Up @@ -4559,14 +4505,7 @@
"title": "Send Completion Message",
"sidebarTitle": "Send Completion Message"
}
},
"x-codeSamples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request POST \\\n --url 'https://{api_base_url}/completion-messages' \\\n --header 'Authorization: Bearer {api_key}' \\\n --header 'Content-Type: application/json' \\\n --no-buffer \\\n --data '{\"inputs\": {\"city\": \"San Francisco\"}, \"response_mode\": \"streaming\", \"user\": \"{user}\"}'"
}
]
}
}
},
"/completion-messages/{task_id}/stop": {
Expand Down Expand Up @@ -6083,14 +6022,7 @@
"title": "Create Document by File",
"sidebarTitle": "Create Document by File"
}
},
"x-codeSamples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request POST \\\n --url 'https://{api_base_url}/datasets/{dataset_id}/document/create-by-file' \\\n --header 'Authorization: Bearer {api_key}' \\\n --form 'file=@quarterly-report.pdf' \\\n --form 'data={\"indexing_technique\":\"high_quality\",\"process_rule\":{\"mode\":\"automatic\"}};type=application/json'"
}
]
}
}
},
"/datasets/{dataset_id}/documents": {
Expand Down Expand Up @@ -7036,14 +6968,7 @@
"title": "Update Document",
"sidebarTitle": "Update Document"
}
},
"x-codeSamples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request PATCH \\\n --url 'https://{api_base_url}/datasets/{dataset_id}/documents/{document_id}' \\\n --header 'Authorization: Bearer {api_key}' \\\n --form 'file=@quarterly-report.pdf' \\\n --form 'data={\"process_rule\":{\"mode\":\"automatic\"}};type=application/json'"
}
]
}
}
},
"/datasets/{dataset_id}/documents/{document_id}/download": {
Expand Down Expand Up @@ -12499,14 +12424,7 @@
"title": "Upload Pipeline File",
"sidebarTitle": "Upload Pipeline File"
}
},
"x-codeSamples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request POST \\\n --url 'https://{api_base_url}/datasets/pipeline/file-upload' \\\n --header 'Authorization: Bearer {api_key}' \\\n --form 'file=@quarterly-report.pdf'"
}
]
}
}
},
"/datasets/{dataset_id}/pipeline/datasource-plugins": {
Expand Down
4 changes: 4 additions & 0 deletions ja/api-reference/guides/streaming.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,10 @@ data: {"event": "workflow_started", "task_id": "c3800678-…", "workflow_run_id"
data: {"event": "node_finished", "task_id": "c3800678-…", "workflow_run_id": "fb47b2e6-…", "data": {…}}
```

<Tip>
curl でテストする場合は、`-N`（`--no-buffer`）を付けます。イベントが実行完了後にまとめてではなく、到着するたびに表示されます。
</Tip>

## イベントタイプごとの振り分け

届くイベントはアプリタイプによって異なります。イベントの一覧は [チャットメッセージを送信](/ja/api-reference/chat-messages/send-chat-message)、[ワークフローを実行](/ja/api-reference/workflow-runs/run-workflow)、[完了メッセージを送信](/ja/api-reference/completion-messages/send-completion-message) の各イベント表を参照してください。
Expand Down
100 changes: 9 additions & 91 deletions ja/api-reference/openapi_service.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -421,14 +421,7 @@
"title": "チャットメッセージを送信",
"sidebarTitle": "チャットメッセージを送信"
}
},
"x-codeSamples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request POST \\\n --url 'https://{api_base_url}/chat-messages' \\\n --header 'Authorization: Bearer {api_key}' \\\n --header 'Content-Type: application/json' \\\n --no-buffer \\\n --data '{\"query\": \"What are the specs of the iPhone 13 Pro Max?\", \"inputs\": {}, \"response_mode\": \"streaming\", \"user\": \"{user}\"}'"
}
]
}
}
},
"/chat-messages/{task_id}/stop": {
Expand Down Expand Up @@ -629,13 +622,6 @@
}
}
},
"x-codeSamples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request GET \\\n --url 'https://{api_base_url}/messages/{message_id}/suggested?user={user}' \\\n --header 'Authorization: Bearer {api_key}'"
}
],
"x-mint": {
"href": "/ja/api-reference/chat-messages/get-next-suggested-questions",
"metadata": {
Expand Down Expand Up @@ -793,14 +779,7 @@
"title": "ファイルをアップロード",
"sidebarTitle": "ファイルをアップロード"
}
},
"x-codeSamples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request POST \\\n --url 'https://{api_base_url}/files/upload' \\\n --header 'Authorization: Bearer {api_key}' \\\n --form 'file=@product-photo.png' \\\n --form 'user={user}'"
}
]
}
}
},
"/files/{file_id}/preview": {
Expand Down Expand Up @@ -1423,13 +1402,6 @@
}
}
},
"x-codeSamples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request GET \\\n --url 'https://{api_base_url}/messages?conversation_id={conversation_id}&user={user}' \\\n --header 'Authorization: Bearer {api_key}'"
}
],
"x-mint": {
"href": "/ja/api-reference/conversations/list-conversation-messages",
"metadata": {
Expand Down Expand Up @@ -2069,14 +2041,7 @@
"title": "音声をテキストに変換",
"sidebarTitle": "音声をテキストに変換"
}
},
"x-codeSamples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request POST \\\n --url 'https://{api_base_url}/audio-to-text' \\\n --header 'Authorization: Bearer {api_key}' \\\n --form 'file=@meeting-question.mp3' \\\n --form 'user={user}'"
}
]
}
}
},
"/text-to-audio": {
Expand Down Expand Up @@ -3683,7 +3648,7 @@
"ワークフロー実行"
],
"summary": "ワークフローイベントをストリーム",
"description": "**対象アプリ**：Chatflow、Workflow。\n\n一時停止後または元の SSE 接続が切断された後にワークフロー実行の Server-Sent Events ストリームを再開します。すでに完了している実行に対しては、`workflow_finished` イベントを 1 つ送信してストリームを閉じます。\n\n進行中の実行のノードレベルのステータスと進捗を確認するには、`include_state_snapshot=true` を指定して呼び出します。ストリームは新しいイベントの送信前に、実行済み各ノードのステータスを再送します。",
"description": "**対象アプリ**：Chatflow、Workflow。\n\n一時停止後または元の SSE 接続が切断された後にワークフロー実行の [Server-Sent Events ストリーム](/ja/api-reference/guides/streaming) を再開します。すでに完了している実行に対しては、`workflow_finished` イベントを 1 つ送信してストリームを閉じます。\n\n進行中の実行のノードレベルのステータスと進捗を確認するには、`include_state_snapshot=true` を指定して呼び出します。ストリームは新しいイベントの送信前に、実行済み各ノードのステータスを再送します。",
"operationId": "streamWorkflowEvents",
"parameters": [
{
Expand Down Expand Up @@ -3783,18 +3748,6 @@
}
}
},
"x-codeSamples": [
{
"lang": "bash",
"label": "Resume stream",
"source": "curl -N --request GET \\\n --url 'https://{api_base_url}/workflow/{workflow_run_id}/events?user={user}' \\\n --header 'Authorization: Bearer {api_key}'"
},
{
"lang": "bash",
"label": "With state snapshot",
"source": "curl -N --request GET \\\n --url 'https://{api_base_url}/workflow/{workflow_run_id}/events?user={user}&include_state_snapshot=true' \\\n --header 'Authorization: Bearer {api_key}'"
}
],
"x-mint": {
"href": "/ja/api-reference/workflow-runs/stream-workflow-events",
"metadata": {
Expand Down Expand Up @@ -4021,14 +3974,7 @@
"title": "ワークフローを実行",
"sidebarTitle": "ワークフローを実行"
}
},
"x-codeSamples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl -N --request POST \\\n --url 'https://{api_base_url}/workflows/run' \\\n --header 'Authorization: Bearer {api_key}' \\\n --header 'Content-Type: application/json' \\\n --data '{\"inputs\": {\"query\": \"Summarize this text: The quick brown fox jumps over the lazy dog.\"}, \"response_mode\": \"streaming\", \"user\": \"{user}\"}'"
}
]
}
}
},
"/workflows/{workflow_id}/run": {
Expand Down Expand Up @@ -4559,14 +4505,7 @@
"title": "完了メッセージを送信",
"sidebarTitle": "完了メッセージを送信"
}
},
"x-codeSamples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request POST \\\n --url 'https://{api_base_url}/completion-messages' \\\n --header 'Authorization: Bearer {api_key}' \\\n --header 'Content-Type: application/json' \\\n --no-buffer \\\n --data '{\"inputs\": {\"city\": \"San Francisco\"}, \"response_mode\": \"streaming\", \"user\": \"{user}\"}'"
}
]
}
}
},
"/completion-messages/{task_id}/stop": {
Expand Down Expand Up @@ -6083,14 +6022,7 @@
"title": "ファイルからドキュメントを作成",
"sidebarTitle": "ファイルからドキュメントを作成"
}
},
"x-codeSamples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request POST \\\n --url 'https://{api_base_url}/datasets/{dataset_id}/document/create-by-file' \\\n --header 'Authorization: Bearer {api_key}' \\\n --form 'file=@quarterly-report.pdf' \\\n --form 'data={\"indexing_technique\":\"high_quality\",\"process_rule\":{\"mode\":\"automatic\"}};type=application/json'"
}
]
}
}
},
"/datasets/{dataset_id}/documents": {
Expand Down Expand Up @@ -7036,14 +6968,7 @@
"title": "ドキュメントを更新",
"sidebarTitle": "ドキュメントを更新"
}
},
"x-codeSamples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request PATCH \\\n --url 'https://{api_base_url}/datasets/{dataset_id}/documents/{document_id}' \\\n --header 'Authorization: Bearer {api_key}' \\\n --form 'file=@quarterly-report.pdf' \\\n --form 'data={\"process_rule\":{\"mode\":\"automatic\"}};type=application/json'"
}
]
}
}
},
"/datasets/{dataset_id}/documents/{document_id}/download": {
Expand Down Expand Up @@ -12499,14 +12424,7 @@
"title": "パイプラインファイルをアップロード",
"sidebarTitle": "パイプラインファイルをアップロード"
}
},
"x-codeSamples": [
{
"lang": "bash",
"label": "cURL",
"source": "curl --request POST \\\n --url 'https://{api_base_url}/datasets/pipeline/file-upload' \\\n --header 'Authorization: Bearer {api_key}' \\\n --form 'file=@quarterly-report.pdf'"
}
]
}
}
},
"/datasets/{dataset_id}/pipeline/datasource-plugins": {
Expand Down
Loading
Loading