fix: remove x-codeSamples so playground examples update live (#1015) (backport to release/1.17.0) - #1018
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. (cherry picked from commit 236fcaa)
Contributor
There was a problem hiding this comment.
Pull request overview
This backport removes hand-written x-codeSamples from the Service API OpenAPI specs so Mintlify’s API playground can auto-generate request examples that update live as users type, and it adds supporting guidance + linting to prevent reintroduction.
Changes:
- Remove
x-codeSamplesblocks from{en,zh,ja}/api-reference/openapi_service.jsonoperations and add an inline link to the SSE streaming guide from the workflow events streaming endpoint description. - Add an SSE streaming guide tip in
{en,zh,ja}/api-reference/guides/streaming.mdxrecommendingcurl -N/--no-buffer. - Update
tools/api-pipeline/lint_specs.pyto flag any operation that includesx-codeSamples, and update the API reference spec conventions accordingly.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| en/api-reference/openapi_service.json | Removes x-codeSamples so the playground uses live auto-generated snippets; adds link to the SSE guide for streaming events. |
| zh/api-reference/openapi_service.json | Same as English spec changes, localized link target. |
| ja/api-reference/openapi_service.json | Same as English spec changes, localized link target. |
| en/api-reference/guides/streaming.mdx | Adds a Tip about using curl -N/--no-buffer for real-time SSE output. |
| zh/api-reference/guides/streaming.mdx | Adds the corresponding translated Tip. |
| ja/api-reference/guides/streaming.mdx | Adds the corresponding translated Tip. |
| tools/api-pipeline/lint_specs.py | Changes linting behavior to forbid x-codeSamples on operations. |
| .claude/skills/dify-docs-api-reference/references/spec-conventions.md | Updates the written convention around x-codeSamples usage/removal. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
164
to
+166
| ## 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). |
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.
Backport
This will backport the following commits from
maintorelease/1.17.0: