feat: generate api reference from dify service schemas

[hyoban]

Summary

The API reference currently maintains its own schemas, which can drift from Dify's Service API. This change generates the English, Chinese, and Japanese specs from a pinned Dify export and applies documentation annotations through language-specific overlays.

The source is the clean Dify main commit cb1a8963e398527e93377834f2f098974f11f825, fetched on September 9, 2026. It includes the merged schema/runtime corrections in langgenius/dify#41943 and the merged rate-limit description fix in langgenius/dify#41975. The snapshot records its repository, full SHA, and checksum. A fresh export from this main commit is byte-identical to the previously imported snapshot, so all three published specs and overlays remain unchanged by the main refresh.

Changes

• Keep the existing 82 published operations, operation IDs, page URLs, and navigation in all three languages. Explicitly exclude the root operation and five deprecated aliases from the upstream export.
• Preserve applicable descriptions, translations, examples, and Mintlify metadata in overlays. Dify owns the API contract: overlays cannot change fields, types, references, required properties, enum values, response statuses, or security.
• Align annotations and examples with the pinned implementation, including paused responses and their resolved defaults, streaming descriptions, metadata filtering, and error responses. Restore valid historical error examples and remove prose pointing to obsolete schemas.
• Add the manual export/import/build/capture workflow, reproducibility checks, OpenAPI 3.1 and example validation, and full contract parity checks. Update the writing and release-sync instructions to use this workflow. A removed overlay target fails the build and requires review.

Review guide

Start with tools/api-pipeline/README.md, build_specs.py, validate_specs.py, and their tests, then review publication.json and the source provenance. The large JSON diff consists of the upstream snapshot, three annotation overlays, and three generated specs. Internal tooling and overlays remain excluded from publication by the existing .mintignore.

For future updates, export from a clean pinned Dify checkout, import and review the contract diff, update annotations in all three languages, capture them, and rebuild and validate before committing the inputs and outputs together. Annotation applicability checks cannot establish that prose still matches runtime behavior; those changes still need code review and rendered-page inspection.

Validation

• Reproducible build: 3 languages, 82 operations each.
• Tool regression tests: 16 passed.
• OpenAPI validation: upstream and all three outputs passed; 704 examples checked per language.
• Documentation lint: 2,097 media examples and 54 links, no issues.
• Contract/language parity and overview coverage: no issues.
• Repository internal-link check: 873 files, 3,664 links, and 716 anchors; no broken links, anchors, or navigation issues.
• Mintlify validation and targeted local preview of JSON/SSE and paused-response pages passed during migration review.
• Paused default examples were checked against the pinned resolver behavior; this is not a live backend integration test.
• git diff --check passed.