Repository navigation
Conversation
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
4 of 5 tasks
hyoban
force-pushed
the
docs/service-api-openapi-contract-alignment
branch
from
August 25, 2026 14:12
3421f1d to
bb220a5
Compare
This was referenced Aug 25, 2026
hyoban
force-pushed
the
docs/service-api-openapi-contract-alignment
branch
from
August 25, 2026 14:25
bb220a5 to
1bd146f
Compare
hyoban
marked this pull request as ready for review
August 25, 2026 14:34
hyoban
marked this pull request as draft
August 25, 2026 14:37
Contributor
There was a problem hiding this comment.
Pull request overview
Documents the Service API generation, locale-overlay, and release-sync workflows.
Changes:
- Adds contract composition, overlay capture, and alignment guidance.
- Updates API reference and release-sync procedures.
- Clarifies lint failure behavior.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.
| File | Review result |
|---|---|
tools/api-pipeline/README.md |
Moderate issue (2 votes): resolve dify_ref.json through $DOCS or change to the repository root before running the command. |
.claude/skills/dify-docs-release-sync/SKILL.md |
Moderate issue (3 votes): add compose_service_api.py compose and contract_alignment.py to the API gate. |
.claude/skills/dify-docs-api-reference/SKILL.md |
Documents generated-contract authoring and overlay verification requirements. |
.claude/skills/dify-docs-api-reference/references/audit-checklist.md |
Moderate issue (3 votes): include overlay capture/recomposition and contract-alignment checks, or delegate to the full pipeline procedure. |
Suppressed comments (7)
.claude/skills/dify-docs-api-reference/SKILL.md:34
- This new source-of-truth rule conflicts with
references/codebase-paths.md:9, which still labels{en,zh,ja}/api-reference/openapi_service.jsonas the “spec of record.” An agent following that referenced mapping can still edit the generated output directly and bypass the overlay workflow; update that mapping in the same change.
Dify's generated `service-openapi.json` is the base contract. The three `{en,zh,ja}/api-reference/openapi_service.json` files are composed authoring outputs: edit presentation fields in all three languages, then recapture their reviewed overlays with `compose_service_api.py capture`. Capture ignores wire-contract edits, so paths, parameters, schemas, statuses, security, and deprecation always come from Dify. The composer applies the locale overlays back to the Dify base, and `parity_check` enforces structural parity with en. Never update an overlay fingerprint without rechecking the affected endpoint against runtime.
.claude/skills/dify-docs-api-reference/SKILL.md:42
- This API-edit checklist requires recapturing overlays but does not explicitly require the compose current-output check or
contract_alignment.py. A caller can therefore satisfy the listed structural gates while leaving a stale composed file or a wire-contract drift undetected. Include the README's generated-spec composition and alignment checks in the mandatory verification sequence.
After any spec edit, recapture and verify the locale overlays per `tools/api-pipeline/README.md`. After structural edits (adding, removing, retitling, or reordering operations, or changing availability), also update `memberships.json` and the app-type overview pages, then run `wire`, `check-coverage`, `lint_specs`, and `parity_check`. Description-only edits need no `wire`.
tools/api-pipeline/README.md:69
- This update procedure does not say to update
dify_ref.jsonwith the newly reviewed ref and the digest of its generatedservice-openapi.json. Normal PR CI uses only that file's pin (seecheck_service_api.yml), so following these steps against a new ref without updating the pin leaves CI validating the old contract.
After reviewing a new Dify ref, compose the current overlays against it:
tools/api-pipeline/README.md:49
- This pasted block does not enable fail-fast execution. If composition returns 1 for an overlay conflict,
contract_alignment.pycan still return 0 because it ignores presentation drift, so the block can appear successful and line 50 is skipped only if the shell is configured specially. Run the sequence with fail-fast handling, and use a trap for worktree cleanup so failures do not leak the detached worktree.
python3 "$DOCS/tools/api-pipeline/compose_service_api.py" compose "$GENERATED_DIR/service-openapi.json"
python3 "$DOCS/tools/api-pipeline/contract_alignment.py" "$GENERATED_DIR/service-openapi.json"
tools/api-pipeline/README.md:84
- The verification block has the same failure-masking problem: a failed
composecan be followed by successful alignment, parity, and lint commands, leaving the pasted sequence with a zero final status even though the composed output is invalid. Add fail-fast shell handling before these commands.
python3 "$DOCS/tools/api-pipeline/compose_service_api.py" compose "$GENERATED_DIR/service-openapi.json"
python3 "$DOCS/tools/api-pipeline/contract_alignment.py" "$GENERATED_DIR/service-openapi.json"
python3 "$DOCS/tools/api-pipeline/parity_check.py"
python3 "$DOCS/tools/api-pipeline/lint_specs.py"
tools/api-pipeline/README.md:59
examplescannot be treated as wholly localized/presentation data here.compose_service_api.pymakesexample/examplesoverlay-owned andcontract_alignment.pyexcludes them from comparison, so a locale overlay can change a request or response payload literal without any gate noticing. This conflicts with the API audit rule that enum and example literals remain verbatim; preserve or validate example values while localizing only labels/prose.
The alignment gate requires zero wire-contract differences: matching OpenAPI versions, exact public path/method coverage, matching deprecation flags, and semantically equivalent effective authentication requirements, parameters, request encodings, request media types, response headers, schemas, and statuses. It also validates schemas against the declared OpenAPI dialect: 3.0 specs cannot use keywords or array-form types outside the OpenAPI 3.0 Schema Object subset, while 3.1 specs cannot use the legacy `nullable` keyword or boolean exclusive bounds. Descriptions, examples, enum ordering, `x-mint`, and `x-codeSamples` are presentation and localization data; any other vendor extension remains part of the compared contract.
tools/api-pipeline/README.md:75
- The tools do not enforce all of the requirements claimed here: composition checks non-empty summary/tags and
x-mintfields, while lint checks examples only for applicable response media types; neither verifies that descriptions or tags are actually localized. Distinguish authoring requirements from automated validation, or add those validators.
Unrelated upstream additions flow into the output. If the new contract touches an overlaid presentation value, review that location and update the localized spec deliberately. New operations require localized summaries, descriptions, tags, examples, and `x-mint` metadata before validation passes.
💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| ```bash | ||
| export DOCS="$(git rev-parse --show-toplevel)" | ||
| python3 "$DOCS/tools/api-pipeline/lint_specs.py" # success = prints "TOTAL ISSUES: 0"; its exit code stays 0 even with issues, so read the count | ||
| python3 "$DOCS/tools/api-pipeline/lint_specs.py" # success = prints "TOTAL ISSUES: 0" and exits 0 |
| 2. Compose the pinned Dify JSON with the current overlays. The generated JSON owns every wire-contract field. Apply presentation fixes to the `en` output, then mirror them into `zh` and `ja` (translate summaries and descriptions; keep wire strings verbatim). Recapture the overlays and rebuild; capture ignores wire-contract edits, and any changed upstream presentation value under an overlay must be reviewed rather than force-refreshed. | ||
| 3. If operations were added, removed, retitled, or reordered: update `tools/api-pipeline/memberships.json` (and the app-type overview pages) if availability changed, then regenerate navigation with `python3 "$DOCS/tools/api-pipeline/merge_specs.py" wire --lang en zh ja` (rewrites the `docs.json` API menus and redirects). Description-only edits skip this step. | ||
| 4. Run the gate from the docs repo root. The gate is each command's printed zero line, not its exit status — `lint_specs.py` exits 0 even with issues. Any nonzero printed count (or nonzero exit) blocks the track — fix and re-run: | ||
| 4. Run the gate from the docs repo root. Each command exits nonzero on failure and also prints its issue count. Any nonzero printed count or nonzero exit blocks the track — fix and re-run: |
| ```bash | ||
| export DIFY_REPO=/path/to/dify | ||
| export DOCS="$(git rev-parse --show-toplevel)" | ||
| export DIFY_REF="$(python3 -c 'import json; print(json.load(open("tools/api-pipeline/dify_ref.json"))["ref"])')" |
This branch was successfully deployed
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.
Summary
Companion backend PR: langgenius/dify#41248
Validation
merge_specs.py wire—docs.jsonunchanged