docs(openapi): describe the schema fields in the spec - #202
docs(openapi): describe the schema fields in the spec#202ariel-formance wants to merge 1 commit into
Conversation
The Orchestration spec declared its workflow, instance, trigger and stage schemas without saying what any of the fields mean. Add descriptions to v1 and v2, and re-merge the root spec.
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars. ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
🛑 Changes requested — automated reviewSeveral added descriptions are ignored because they are siblings of |
NumaryBot
left a comment
NumaryBot
left a comment
There was a problem hiding this comment.
NumaryBot posted 1 new inline finding.
Summary: #202 (comment)
| balance: | ||
| type: string | ||
| description: Name of the balance within the wallet. Defaults to the main balance when omitted | ||
| StageSendDestinationWallet: |
There was a problem hiding this comment.
🟠 [major] Wrap described references in schema objects
Because this is OpenAPI 3.0.3, siblings of a $ref Reference Object are ignored by compliant tooling, so this description—and the other newly described direct references such as ActivityStripeTransfer and their v2 equivalents—will not appear in generated documentation or SDK comments. Wrap each reference with allOf and place the description on the containing schema instead.
2 participants
Why
The Orchestration OpenAPI spec declares its schemas without saying what any of the fields mean, so the generated SDKs ship bare field names and the API reference renders a name and a type with no explanation.
What
Adds
descriptionto the schema fields inopenapi/v1.yamlandopenapi/v2.yaml— workflows and their configs, instances, stages, triggers, and the error and cursor types.openapi.yamlis regenerated from those two plus the overlay, asjust openapidoes. It is a pure addition (454 lines added, none removed) with no reformatting of the existing content, so the Dirty check sees no churn beyond the new descriptions.No structural changes: no fields added or removed, no types or required-ness touched, so generated clients keep the same shape and only pick up doc comments.
Part of a sweep doing the same across the module specs.