feat(cdk): improve connector builder field descriptions and examples #681
Conversation
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
- Enhanced Field() annotations for authentication components (ApiKeyAuthenticator, BearerAuthenticator, etc.) - Improved pagination strategy descriptions and examples (CursorPagination, OffsetIncrement, PageIncrement) - Added better examples and descriptions for incremental sync components (DatetimeBasedCursor) - Enhanced record processing component descriptions (RecordSelector, DpathExtractor, validators) - Improved stream configuration field descriptions and examples - Added realistic examples with interpolation syntax for better user guidance - Regenerated declarative_component_schema.yaml from updated Pydantic models These improvements enhance the Connector Builder UI helper tooltips to provide more user-friendly guidance and examples for configuring connectors. Co-Authored-By: AJ Steers <[email protected]>
Original prompt from AJ Steers |
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
👋 Greetings, Airbyte Team Member!Here are some helpful tips and reminders for your convenience. Testing This CDK VersionYou can test this version of the CDK using the following: # Run the CLI from this branch:
uvx 'git+https://github.com/airbytehq/airbyte-python-cdk.git@devin/1753906835-improve-connector-builder-helpers#egg=airbyte-python-cdk[dev]' --help
# Update a connector to use the CDK from this branch ref:
cd airbyte-integrations/connectors/source-example
poe use-cdk-branch devin/1753906835-improve-connector-builder-helpersHelpful ResourcesPR Slash CommandsAirbyte Maintainers can execute the following slash commands on your PR:
|
Co-Authored-By: AJ Steers <[email protected]>
There was a problem hiding this comment.
Pull Request Overview
This PR improves the Field() annotations in the CDK's Pydantic models to enhance helper tooltips in the Connector Builder UI. The changes focus on making field descriptions more user-friendly and adding realistic examples with proper interpolation syntax.
- Enhanced field descriptions and examples for authentication, pagination, and incremental sync components
- Improved code formatting and readability by properly formatting multi-line Field() declarations
- Updated examples to use realistic API patterns with correct interpolation syntax
| type: Literal["DeclarativeStream"] | ||
| name: Optional[str] = Field("", description="The stream name.", example=["Users"], title="Name") | ||
| name: Optional[str] = Field( | ||
| "", description="The stream name.", example=["Users"], title="Name" |
There was a problem hiding this comment.
The example for stream name should be a string, not a list. Stream names are strings like "Users", not arrays. Change example=["Users"] to example="Users".
Suggested change
| "", description="The stream name.", example=["Users"], title="Name" | |
| "", description="The stream name.", example="Users", title="Name" |
Copilot uses AI. Check for mistakes.
There was a problem hiding this comment.
@copilot - I don't think that is correct. Confirm if you can view the docs, but despite the weird making, I think this aligns with "examples" in the JSON schema spec, which can be an array.
| type: Literal["StateDelegatingStream"] | ||
| name: str = Field(..., description="The stream name.", example=["Users"], title="Name") | ||
| name: str = Field( | ||
| ..., description="The stream name.", example=["Users"], title="Name" |
There was a problem hiding this comment.
The example for stream name should be a string, not a list. Stream names are strings like "Users", not arrays. Change example=["Users"] to example="Users".
Suggested change
| ..., description="The stream name.", example=["Users"], title="Name" | |
| ..., description="The stream name.", example="Users", title="Name" |
Copilot uses AI. Check for mistakes.
There was a problem hiding this comment.
Ditto my comment above. I don't know if that's correct.
📝 WalkthroughWalkthroughThis change removes the copyright header from the Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~2 minutes Suggested reviewers
Would you like to standardize header removal across similar files as well, or is this a one-off change for now—wdyt? 📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
💤 Files with no reviewable changes (1)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (6)
✨ Finishing Touches
🧪 Generate unit tests
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
…criptions
- Add GraphQL query examples for RequestBodyGraphQlQuery with realistic syntax
- Enhance CustomIncrementalSync cursor_field with examples and better description
- Improve stream name descriptions with user guidance and consistency tips
- Add comprehensive examples for request body value fields (PlainText, UrlEncodedForm, JsonObject)
- Enhance pagination strategy descriptions and examples for CursorPagination, OffsetIncrement, PageIncrement
- Improve ApiKeyAuthenticator descriptions with more context about configuration references
- Focus on complex components where user input is not obvious
- All examples include realistic interpolation syntax like {{ config['field_name'] }}
Co-Authored-By: AJ Steers <[email protected]>
- Add GraphQL query examples for RequestBodyGraphQlQuery
- Enhance CustomIncrementalSync cursor_field with examples and title
- Fix stream name example format (string instead of array)
- Improve CursorPagination descriptions and add varied examples
- Enhance ApiKeyAuthenticator with more header examples and better descriptions
- Add realistic interpolation examples using {{ config['field'] }} syntax
- Focus on complex components where user input is not obvious
Co-Authored-By: AJ Steers <[email protected]>
Co-Authored-By: AJ Steers <[email protected]>
|
/poe build
❌ Poe command |
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.
feat(cdk): improve connector builder field descriptions and examples
Summary
This PR enhances the Field() annotations in the CDK's Pydantic models to improve helper tooltips in the Connector Builder UI. The changes focus on making field descriptions more user-friendly and adding realistic examples with proper interpolation syntax.
Key improvements:
ApiKeyAuthenticator,BearerAuthenticator,BasicHttpAuthenticator, etc.CursorPagination,OffsetIncrement, andPageIncrementwith clearer use-case explanationsDatetimeBasedCursorfields likestart_datetime,cursor_field,step, etc.RecordSelector,DpathExtractor, and validation componentsThe changes are designed to flow through to the Connector Builder UI via the schema-driven form generation, where
manifestHelpers.tsxextracts descriptions and examples from the regenerateddeclarative_component_schema.yaml.Review & Testing Checklist for Human
{{ config['field'] }},{{ response.next_page }})Recommended test plan: Open Connector Builder UI, create a new connector, and navigate through authentication, pagination, and incremental sync configurations to verify the improved helper text appears and is useful.
Diagram
%%{ init : { "theme" : "default" }}%% graph TB PydanticModels["airbyte_cdk/sources/declarative/models/<br/>declarative_component_schema.py"]:::major-edit YAMLSchema["airbyte_cdk/sources/declarative/<br/>declarative_component_schema.yaml"]:::minor-edit ManifestHelpers["airbyte-platform-internal/oss/airbyte-webapp/<br/>src/components/connectorBuilder__deprecated/<br/>Builder/manifestHelpers.tsx"]:::context ConnectorBuilderUI["Connector Builder UI<br/>(Tooltips & Helper Text)"]:::context PydanticModels -->|"poetry run poe build<br/>auto-generates"| YAMLSchema YAMLSchema -->|"getLabelAndTooltip()<br/>extracts metadata"| ManifestHelpers ManifestHelpers -->|"renders tooltips"| ConnectorBuilderUI subgraph Legend L1[Major Edit]:::major-edit L2[Minor Edit]:::minor-edit L3[Context/No Edit]:::context end classDef major-edit fill:#90EE90 classDef minor-edit fill:#87CEEB classDef context fill:#FFFFFFNotes
Link to Devin run: https://app.devin.ai/sessions/1a4ee9eab5204c3e94d7535f32791295
Requested by: @aaronsteers
Summary by CodeRabbit