fix: remove x-codeSamples so playground examples update live - #1015
Merged
Conversation
Hand-written x-codeSamples blocks on 11 endpoints replaced Mintlify's auto-generated request samples with static cURL, so the playground ignored typed values and offered no other language tabs. Headless-browser tests confirmed autogen now covers every case they were added for: multipart renders --form samples and typed values appear live in all snippet languages. Remove all 33 blocks (en/zh/ja), invert the lint guard to flag any x-codeSamples occurrence, rewrite the spec-conventions rule, add a curl -N tip to the SSE streaming guide (the only content the removed samples uniquely carried), and link the guide from the Stream Workflow Events description.
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR removes operation-level x-codeSamples from the localized Service API OpenAPI specs so Mintlify’s API playground can resume generating live, multi-language request snippets (reflecting typed values), and it adds/updates guardrails and guidance to prevent x-codeSamples from being reintroduced.
Changes:
- Remove all
x-codeSamplesblocks from{en,zh,ja}/api-reference/openapi_service.jsonand add an inline link to the Streaming guide from “Stream Workflow Events”. - Add a Streaming guide Tip in all three languages documenting
curl -N/--no-bufferfor real-time SSE output. - Update
tools/api-pipeline/lint_specs.pyand the internal spec conventions to flag and forbid anyx-codeSamplesusage.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| en/api-reference/openapi_service.json | Removes x-codeSamples and links Stream Workflow Events to the Streaming guide so the playground can autogenerate live snippets. |
| zh/api-reference/openapi_service.json | Same as English: removes x-codeSamples and adds the Streaming guide link in the Stream Workflow Events description. |
| ja/api-reference/openapi_service.json | Same as English: removes x-codeSamples and adds the Streaming guide link in the Stream Workflow Events description. |
| en/api-reference/guides/streaming.mdx | Adds a Tip to use curl -N/--no-buffer when testing SSE streams. |
| zh/api-reference/guides/streaming.mdx | Adds the localized Tip for curl -N/--no-buffer. |
| ja/api-reference/guides/streaming.mdx | Adds the localized Tip for curl -N/--no-buffer. |
| tools/api-pipeline/lint_specs.py | Inverts the previous guard: now emits an issue whenever an operation includes x-codeSamples. |
| .claude/skills/dify-docs-api-reference/references/spec-conventions.md | Updates the spec conventions to prohibit x-codeSamples and points SSE guidance to the Streaming guide. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
This was referenced Sep 1, 2026
Contributor
Author
💚 All backports created successfully
Questions ?Please refer to the Backport tool documentation and see the Github Action logs for details |
RiskeyL
added a commit
that referenced
this pull request
Sep 1, 2026
…1018) Hand-written x-codeSamples blocks on 11 endpoints replaced Mintlify's auto-generated request samples with static cURL, so the playground ignored typed values and offered no other language tabs. Headless-browser tests confirmed autogen now covers every case they were added for: multipart renders --form samples and typed values appear live in all snippet languages. Remove all 33 blocks (en/zh/ja), invert the lint guard to flag any x-codeSamples occurrence, rewrite the spec-conventions rule, add a curl -N tip to the SSE streaming guide (the only content the removed samples uniquely carried), and link the guide from the Stream Workflow Events description. (cherry picked from commit 236fcaa)
RiskeyL
added a commit
that referenced
this pull request
Sep 1, 2026
…1017) Hand-written x-codeSamples blocks on 11 endpoints replaced Mintlify's auto-generated request samples with static cURL, so the playground ignored typed values and offered no other language tabs. Headless-browser tests confirmed autogen now covers every case they were added for: multipart renders --form samples and typed values appear live in all snippet languages. Remove all 33 blocks (en/zh/ja), invert the lint guard to flag any x-codeSamples occurrence, rewrite the spec-conventions rule, add a curl -N tip to the SSE streaming guide (the only content the removed samples uniquely carried), and link the guide from the Stream Workflow Events description. (cherry picked from commit 236fcaa)
RiskeyL
added a commit
that referenced
this pull request
Sep 1, 2026
…1016) Hand-written x-codeSamples blocks on 11 endpoints replaced Mintlify's auto-generated request samples with static cURL, so the playground ignored typed values and offered no other language tabs. Headless-browser tests confirmed autogen now covers every case they were added for: multipart renders --form samples and typed values appear live in all snippet languages. Remove all 33 blocks (en/zh/ja), invert the lint guard to flag any x-codeSamples occurrence, rewrite the spec-conventions rule, add a curl -N tip to the SSE streaming guide (the only content the removed samples uniquely carried), and link the guide from the Stream Workflow Events description. (cherry picked from commit 236fcaa)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
On the 11 endpoints carrying hand-written
x-codeSamples(Send Chat Message, Run Workflow, the upload endpoints, …), the API playground's request example never reflected typed values, and readers got no language tab other than cURL: a static sample replaces Mintlify's auto-generated snippets for the whole operation. The samples date from when autogen couldn't express multipart bodies or SSE flags. Headless-browser tests against the live site and the local preview show autogen now covers all of it: proper--formsamples for multipart, typed values appearing live, and the full set of language tabs.Changes
{en,zh,ja}/api-reference/openapi_service.json: remove all 11x-codeSamplesblocks per language, and link the SSE Streaming guide inline from the Stream Workflow Events description (its removed sample was that page's only route to the curl streaming flag).{en,zh,ja}/api-reference/guides/streaming.mdx: add a Tip — pass-N(--no-buffer) when testing with curl — the one piece of content the removed SSE samples uniquely carried.tools/api-pipeline/lint_specs.py: invert the guard; it used to requirex-codeSampleson GETs with required query params, it now flags any occurrence so the freeze can't be reintroduced..claude/skills/dify-docs-api-reference/references/spec-conventions.md: rewrite thex-codeSamplesrule to match.Verification
lint_specs.py→TOTAL ISSUES: 0(54 links validated);parity_check.py→TOTAL PARITY ISSUES: 0; coverage check clean.default(they appear once typed); the parameter panel's Required badges and the parameter descriptions carry required-ness.Notes
Closes DC-271