feat: align service api with generated contract

[hyoban]

Summary

• align the English, Chinese, and Japanese Service API specs with the contract generated from Dify merge commit 1c6f0a0388262976aa34f8e6a5e3a788cea13f14 (dify#41274)
• take paths, methods, parameters, request and response schemas, status codes, authentication, deprecation flags, operation IDs, and code-owned semantics from the generated JSON
• consume the upstream restoration of 13 verified historical response declarations and the split task-stop request schemas
• preserve pre-existing docs-only content exactly when its generated node remains identifiable, including localized presentation and response examples
• carry presentation content across generated schema extraction or reference changes only when every matching source agrees
• keep the six generator-only operations in the contract without adding x-mint navigation or docs-authored presentation; only prefix their generated internal links for locale-aware validation
• limit the PR diff to the three localized openapi_service.json files

Validation

• mint validate
• exact generated wire match for paths, components, and security in en/zh/ja
• OpenAPI parity: 0 issues
• OpenAPI lint: 0 issues across 1,326 examples and 57 links
• restored-response audit: all 13 upstream response declarations retain their existing localized docs examples
• generator-only operation audit: 6 operations match generated presentation, carry no x-mint, and GET / remains hidden
• overview coverage: 0 failures
• Dify code coverage matrix: 88 code operations and 88 documented operations, with no missing, ghost, or parameter mismatch entries
• git diff --check

Upstream ownership

dify#41274 is merged. The generated contract now owns the selected runtime semantics that were previously recovered from dify-docs, including:

• field and schema descriptions for Agent thought labels, system parameters, Human Input option/default sources, completion metadata, dataset retrieval and ranking configuration, segment and hit-testing payloads, model-provider status fields, and pipeline run responses
• all 13 verified historical 404 or 503 response declarations
• distinct task-stop request schemas for chat/completion and workflow user behavior

The docs repository continues to own Mintlify navigation (x-mint), localized navigation and links, localized presentation, reviewed examples, tutorial-oriented code samples, and deployment-specific server presentation. The file-preview media type remains */* because that is the generated contract; changing it to application/octet-stream should happen upstream if the runtime contract is narrowed later. Canonical test-backed examples can also move upstream incrementally.

Remaining upstream candidates

This PR intentionally preserves the existing docs overlay. Follow-up changes in the Dify repository could further reduce that overlay and prevent the generated contract from drifting:

• Public API surface: exclude GET / from the public Service API specification if it is not a supported API operation. For the five underscore-form compatibility aliases, either exclude them or mark them as deprecated and document their canonical replacements upstream.
• Schema semantics: move the remaining field behavior into the source schemas. The English overlay currently supplies 678 component-schema descriptions missing from the generated file and refines another 122, including defaults, nullable conditions, state meanings, conditional fields, Human Input value resolution, and Dataset/Document/Chunk indexing behavior.
• Endpoint and error semantics: source the remaining runtime behavior from Dify. The overlay currently refines 75 operation descriptions, 115 parameter descriptions, 17 request-body or inline request descriptions, 146 response descriptions, and 9 inline response descriptions. High-value cases include chat error conditions, file access and upload failures, Knowledge API permissions and quotas, pipeline published/draft behavior, pagination cursors, and task/user scoping.
• Portable OpenAPI presentation: consider generating the 18 business tags, structured app-mode availability such as x-dify-app-modes, the distinction between app and knowledge API keys, and canonical request/response examples. The docs overlay currently carries 275 example blocks and 3 single-value examples.

Locale-specific links and translations, x-mint, tutorial-oriented code samples, and the deployment-specific https://{api_base_url} server presentation should remain in dify-docs.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
dify-ce-cloud-docs	🟢 Ready	View Preview	Aug 26, 2026, 12:47 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[Copilot]

Pull request overview

This PR updates the Service API documentation pipeline to align {en,zh,ja}/api-reference/openapi_service.json with a Dify-generated service-openapi.json wire contract, while preserving docs-owned presentation fields and adjusting navigation to hide deprecated operations.

Changes:

• Add a migration-stage aligner (align_service_api.py) plus unit tests to deterministically merge generated wire fields with localized presentation.
• Record the pinned upstream source (repo/commit) and generated contract digest in service_api_source.json, and document the alignment workflow in the API pipeline README.
• Update navigation/redirect wiring to surface GET / (API info) and remove deprecated operations from menus.

Reviewed changes

Copilot reviewed 6 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tools/api-pipeline/test_align_service_api.py	Adds unit tests covering wire-vs-presentation ownership, root endpoint metadata, translation fallback behavior, and deprecated alias handling.
tools/api-pipeline/service_api_source.json	Records the upstream Dify commit and the expected SHA-256 of the generated service-openapi.json.
tools/api-pipeline/README.md	Updates pipeline documentation to describe generated-contract alignment and new tooling inputs.
tools/api-pipeline/merge_specs.py	Excludes deprecated operations from the operation iterator used for docs navigation wiring/coverage checks.
tools/api-pipeline/align_service_api.py	Introduces the alignment tool that merges generated wire contract with locale presentation fields and verifies alignment determinism.
docs.json	Adjusts API navigation pages and redirect ordering, including adding GET / and removing deprecated operations from menus.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.