3757 docs - Embedded guide and API reference, plus the OpenAPI spec fixes behind them - #5571
Merged
Conversation
Field Mapping gets comingSoon frontmatter, which renders both the badge and the callout without any change to the body. Unified API already carried comingSoon; drop it from the sidebar the way the distributed page was hidden. It is listed in two metas - the parent flattens the build folder - so both need the entry removed for the page to actually disappear from the nav. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWSX2tatFegkBoWULoekeU
Nothing documented how a Connected User record actually comes into existence or how to attach your own data to it. The page opens by rejecting the word in its own title: "syncing" is push-shaped, and the mechanism is pull-shaped. There is no create endpoint, no bulk import and no way to pre-provision - ByteChef learns a user exists the first time that user authenticates, and enrichment happens afterwards. Most of the page is the PATCH surface, where the storage shape leaks through the free-form JSON body: name and email are promoted to real columns only when the value is a string, everything else is stringified because metadata values are text, the merge is additive so a key can never be removed, and null is discarded before the merge rather than overwriting. None of that is predictable from the OpenAPI schema, which says only additionalProperties. Lives in Initial Setup rather than under Connected Users because Monitor documents the console and this documents what your backend writes. The console page and the quick-start callout now link here for depth; the callout keeps ownership of the auto-creation fact. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWSX2tatFegkBoWULoekeU
getConnections was declared at a literal /externalUserId segment while also declaring externalUserId as a required path parameter, so the generator emitted @PathVariable("externalUserId") against a route template holding no such variable. The operation is implemented in ConnectionApiController, so the endpoint could not have bound a request. Restore the braces. disableIntegrationInstanceWorkflow declared jwtBearerAuth while sitting on an {externalUserId} path, opposite to the enable twin on the very same path. A JWT names the user through its sub claim and needs no such segment, so the path was right and the security block was wrong. Six connected-user workflow operations declared no security at all, and the execution and webhook specs declared none anywhere - no schemes, no requirements. Declare them: Actions and Tools accept either credential because their paths carry the user id, while App Events and Request Trigger carry none and so take only a JWT. Every embedded operation now declares security, and the declared scheme agrees with the path shape in all 45 cases. The regenerated sources are limited to the seven files carrying a real change; the other 49 differed only in the @generated date stamp. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HWSX2tatFegkBoWULoekeU
|
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
1 participant
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.
Documentation work on the embedded guide and the API reference, plus the OpenAPI spec fixes that came out of it.
The API reference was empty
generate:openapihad produced zero pages since it was introduced. Theautomation-bridgeentry pointed atembedded-configuration-admin-rest, a module that has never existed in this repository; the generator reads every spec up front, so that oneENOENTaborted the run and nothing was written. Fumadocs then rendered the three separators inopenapi/meta.jsonwith nothing beneath them — which is what both production and a local dev server showed.Because the deploy pipeline runs
next buildwithout the generate step, the site kept shipping successfully with the whole section missing.npm run lintgoes from 24 errors to 0, and 21 spec groups now generate.Server changes
One commit touches specs rather than docs, and it fixes a real defect:
getConnectionswas unbindable. It was declared at a literal/externalUserId/...segment while also declaringexternalUserIdas a required path parameter, so the generator emitted@PathVariable("externalUserId")against a route template with no such variable. The operation is implemented inConnectionApiController, so the endpoint could not have bound a request.disableIntegrationInstanceWorkflowdeclaredjwtBearerAuthwhile sitting on an{externalUserId}path, opposite to itsenabletwin on the identical path.Regenerated sources are limited to the seven files carrying a real change; the other 49 differed only in the
@Generateddate stamp.Reference split by audience
Every embedded resource is reachable two ways and the reference interleaved them. It now has Backend (API Key) and Frontend (Signing Key JWT) folders under one Embedded separator, derived from the security the specs declare. Twin counts come out matched across every shared resource — 12/12, 4/4, 2/2, 1/1.
New pages
Comparing the guide against Prismatic's and Paragon's showed we document the happy path well and say almost nothing about failure — a grep for "troubleshoot" or "retry" across the embedded tree returned nothing.
Tenant-Isolated Security was merged into White-Label Execution with a redirect to the anchor.
Notes for review
b1a61e91a09is the one to look at closely — it changes a public route. That route was unbindable as declared, so nothing can have depended on it..gitignorecommit is unrelated to content: the repo-wide Gradle**/build/rule swallows the docs' content section literally namedbuild, sogit addsilently skipped new pages there.Verification
npm run generate:openapiexits 0 from a clean slate, producing 21 groupsnpm run lint(link + fragment validation): 0 errorsnpm run coming-soon: no drift🤖 Generated with Claude Code
https://claude.ai/code/session_01HWSX2tatFegkBoWULoekeU