Skip to content

docs: document service api generation workflow - #968

Closed
hyoban wants to merge 1 commit into
feat/service-api-contract-cifrom
docs/service-api-openapi-contract-alignment
Closed

hyoban wants to merge 1 commit into
feat/service-api-contract-cifrom
docs/service-api-openapi-contract-alignment

Conversation

@hyoban

@hyoban hyoban commented Aug 25, 2026 •

Copy link
Copy Markdown
Member

Summary

  • document the generated-contract and locale-overlay workflow for Service API references
  • update the API reference skill to require overlay capture and verification after spec edits
  • update the release-sync skill to compose the pinned Dify contract before applying presentation changes
  • clarify that lint failures return a nonzero exit code

Companion backend PR: langgenius/dify#41248

Validation

  • 62 unit tests passed
  • coverage check — 0 failures
  • spec lint — 1,857 examples and 644 links checked, 0 issues
  • parity check — 0 issues
  • merge_specs.py wire — docs.json unchanged

@mintlify

mintlify Bot commented Aug 25, 2026 •

Copy link
Copy Markdown
Contributor

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

Project Status Preview Updated (UTC)
dify-ce-cloud-docs 🟢 Ready View Preview Aug 25, 2026, 8:28 AM

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

@hyoban
hyoban force-pushed the docs/service-api-openapi-contract-alignment branch from bb220a5 to 1bd146f Compare August 25, 2026 14:25
@hyoban
hyoban marked this pull request as ready for review August 25, 2026 14:34
@hyoban
hyoban requested a review from RiskeyL as a code owner August 25, 2026 14:34
Copilot AI lite review requested due to automatic review settings August 25, 2026 14:34
@dosubot dosubot Bot added size:M This PR changes 30-99 lines, ignoring generated files. documentation Improvements or additions to documentation labels Aug 25, 2026
@hyoban
hyoban marked this pull request as draft August 25, 2026 14:37

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.json as 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.json with the newly reviewed ref and the digest of its generated service-openapi.json. Normal PR CI uses only that file's pin (see check_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.py can 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 compose can 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

  • examples cannot be treated as wholly localized/presentation data here. compose_service_api.py makes example/examples overlay-owned and contract_alignment.py excludes 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-mint fields, 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"])')"
@hyoban hyoban closed this Aug 25, 2026
@RiskeyL
RiskeyL deleted the docs/service-api-openapi-contract-alignment branch October 26, 2026 07:34

This branch was successfully deployed

1 active deployment
staging — 1bd146f9 Deployed Aug 25, 2026 by mintlify[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation size:M This PR changes 30-99 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants