mirror of
https://github.com/langgenius/dify-docs.git
synced 2026-07-22 12:25:45 -04:00
Riskey
a1e7a7dcb3
* feat: retire the merge pipeline and delete the legacy source specs
openapi_service.json is now the spec of record per language, edited directly. The build/relink modes, resolutions.json, and overrides/ that consolidated the five per-app-type specs are recoverable from git history when Phase 2 rebuilds the spec from the upstream-generated source.
* fix: make parity_check exit nonzero on failures
* docs: document the direct-edit spec workflow in skills and translation guides
* fix: correct the Service API reference against the code-verified audit
Applies the confirmed findings of a full per-operation audit against dify 3c8e0e2113 / graphon 0.6.0: 9 factual errors (availability lines, phantom fields, wrong enum values, inert parameters, wrong error messages), ~33 omitted-error and example-accuracy gaps, the rate_limit_error recharacterization, provider-identifier format documentation, and New Agent availability on the endpoints its Chat Features support (verified end-to-end in code).
* docs: document New Agent's full endpoint surface in the API guides
* translate: propagate the Service API audit fixes to zh and ja
* docs: rewrite Upload File as the readability pilot
Worked example of the API readability standard: contract-first description, facts on the fields (category size limits with env-var link, blacklist rule), real error triggers (415 corrected to its actual cause), template user sentence, source links on sourceable values, and a hand-written multipart cURL sample. Applied to en/zh/ja.
* docs: update spec-conventions for the live link scheme and code samples
* docs: apply the readability standard across the Service API reference
Rewrites all 82 operations to the agreed standard in en/zh/ja: contract-first descriptions, facts on the fields, trigger-led error bullets, template sentences (user, pagination, provider identifiers), source links on sourceable values, guide links instead of inline concept re-explanations, cURL samples where the playground autogen fails (multipart, SSE), a paragraph ceiling everywhere, and restructured streaming narratives (events-by-app-type map; details stay in the event tables). Also folds in two fact corrections surfaced during review: the legacy securitySchemes text and the stale Cloudflare-timeout claim in response_mode, now using the hedged edge-proxy wording.
* docs: codify the readability standard and audit method in the API skill
* fix: apply the audit-verified corrections deferred from the readability pass
Small factual items evidenced in the audit findings that the readability pass could not touch under its fact-freeze: real wire messages (audio 413, type_mismatch number, dynamic run-by-id 404, werkzeug 500/403 strings, annotation 404 punctuation), schema precision (format: uuid, minimum: 1, six missing Get Available Models response fields), and behavioral completeness (document download/zip/delete 404 message variants, tag_ids silent-ignore note, request-scoped batch-metadata lock wording, reasoning_chunk message_id: null, form default key absent not null). Applied to en/zh/ja; parity 0.
* fix: make spec checkers target openapi_service.json explicitly
After the legacy specs were deleted, the openapi_*.json globs in parity_check and lint_specs would silently pass (match nothing, report 0 issues, exit 0) if the spec of record went missing, and would pick up unintended future openapi_*.json files. Both now name openapi_service.json per language and exit 1 when it is absent.
* fix: address Copilot review on pipeline tooling and example titles
Normalizes example summary separators to the dominant "Request Example - Mode" form (the convention doc had drifted, and 4 em-dash outliers existed per language); lint_specs no longer re-reads the spec it already loaded; all spec reads use explicit UTF-8; coverage_matrix and swagger_diff target openapi_service.json explicitly; README and docstring usage resolve DOCS from the git root so the commands work from any directory.
* fix: use context managers for all pipeline file reads
Copilot flagged unclosed handles in the three checkers; applied consistently across all five pipeline scripts (merge_specs and coverage_matrix had the same pattern unflagged).
* fix: report missing spec ops as coverage failures instead of crashing
* fix: print the full relative path in the parity missing-file message
(cherry picked from commit 6aa0ae4661)
API Pipeline
Tooling for the Service API reference. {lang}/api-reference/openapi_service.json is the hand-maintained spec of record per language: edit it directly. The Phase-1 merge machinery (build/relink modes, resolutions.json, overrides/) that consolidated the five legacy per-app-type specs is retired; recover it from git history when Phase 2 rebuilds the spec from R&D's generated spec plus docs-owned overlays.
Layout
| File | Role |
|---|---|
merge_specs.py |
wire (docs.json API menus + redirects) and check-coverage modes |
nav_labels.json |
Guides layout, two-tier reference config, per-group op ordering |
memberships.json |
App type → supported operations; drives the app-type overview pages and the coverage check |
lint_specs.py |
Example/schema, enum, link, and x-codeSamples lint |
parity_check.py |
en/zh/ja structural parity (ops, params, responses, samples) |
coverage_matrix.py, swagger_diff.py |
Code-vs-spec audit tooling, for runtime verification (read openapi_service.json) |
Usage
export DOCS="$(git rev-parse --show-toplevel)"
python3 "$DOCS/tools/api-pipeline/merge_specs.py" wire --lang en zh ja
python3 "$DOCS/tools/api-pipeline/merge_specs.py" check-coverage --lang en zh ja
python3 "$DOCS/tools/api-pipeline/lint_specs.py"
python3 "$DOCS/tools/api-pipeline/parity_check.py"
All checks exit nonzero on failure.
Editing the spec
- Edit all three languages;
parity_checkenforces structural parity with en. - Every operation carries
x-mint.href = /{lang}/api-reference/{en-tag-kebab}/{en-summary-kebab}(English slugs in every language, so the language switcher can map pages) andx-mint.metadata.title/sidebarTitle= the translated summary (without them, the custom href makes Mintlify label the sidebar from the English slug). Set all of these when adding an operation. - The
tagsarrays must stay index-aligned across languages;wiremaps translated tag labels by position and fails on a mismatch. - Shared endpoints exist once, with availability lines and mode notes in the description; there is no cross-spec propagation anymore.
- After adding, removing, retitling, or reordering operations: update
memberships.json(and the app-type overview pages) if availability changed, then runwire,check-coverage, and the lints. Description-only edits need nowire.
URL scheme
/{lang}/api-reference/{en-tag-kebab}/{en-summary-kebab}. Legacy URLs are covered by wire-generated redirects: a catch-all to the English API home plus three knowledge-base exceptions embedded in the product UI.