docs: add note about required write-only field #609
Conversation
WalkthroughThe pull request updates the documentation for request validation, specifically regarding the use of Go struct tags for JSON Schema generation. It clarifies the handling of optional and required fields, expands on nullability, and introduces new sections on validation tags and advanced validation. The documentation now also addresses the behavior of Changes
Assessment against linked issues
Possibly related PRs
Poem
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
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 (
|
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #609 +/- ##
=======================================
Coverage 92.83% 92.83%
=======================================
Files 22 22
Lines 3923 3923
=======================================
Hits 3642 3642
Misses 236 236
Partials 45 45 ☔ View full report in Codecov by Sentry. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Outside diff range and nitpick comments (4)
docs/docs/features/request-validation.md (4)
Line range hint
78-138: Great addition of validation tags and formats!The new tables provide a comprehensive list of validation tags and built-in string formats, which will be extremely helpful for users implementing request validation.
Consider adding a brief introductory sentence before each table to improve readability. For example:
"The following table lists the additional tags supported on model fields, along with their descriptions and examples:"🧰 Tools
🪛 Markdownlint
150-150: Expected: fenced; Actual: indented
Code block style(MD046, code-block-style)
Line range hint
140-151: Valuable clarification onreadOnlyandwriteOnlyfields!This new section provides important information about the behavior of
readOnlyandwriteOnlyfields, which is crucial for proper API design and implementation.To further improve clarity, consider adding a brief example demonstrating the use of
omitemptywithrequired:"true"for a write-only field. This would help illustrate the note at the end of the section.🧰 Tools
🪛 Markdownlint
150-150: Expected: fenced; Actual: indented
Code block style(MD046, code-block-style)
Line range hint
153-176: Excellent explanation of strict vs. loose field validation!This new section clearly explains the default behavior of field validation and provides guidance on how to implement loose validation when needed. The example is helpful for understanding the concept.
Consider adding a brief note about the potential security implications of using
additionalProperties:"true", as it may introduce unexpected data into the system. This would help developers make informed decisions about when to use loose validation.🧰 Tools
🪛 Markdownlint
150-150: Expected: fenced; Actual: indented
Code block style(MD046, code-block-style)
Line range hint
178-189: Good introduction to advanced validation options!This new section provides valuable information about additional validation rules available for custom JSON Schemas.
To enhance this section:
- Consider adding brief examples for each of the listed schema fields (
not,oneOf,anyOf,allOf) to illustrate their usage.- Expand on the note about using custom resolvers, perhaps providing a link to the relevant documentation section.
These additions would give developers a better starting point for implementing advanced validation rules.🧰 Tools
🪛 Markdownlint
150-150: Expected: fenced; Actual: indented
Code block style(MD046, code-block-style)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
- docs/docs/features/request-validation.md (1 hunks)
🧰 Additional context used
🪛 Markdownlint
docs/docs/features/request-validation.md
150-150: Expected: fenced; Actual: indented
Code block style(MD046, code-block-style)
🔇 Additional comments (1)
docs/docs/features/request-validation.md (1)
Line range hint
31-76: Excellent clarification on nullability!The expanded "Nullable" section provides clear and detailed information about how nullability is determined for different field types. The step-by-step logic and examples greatly enhance understanding of this complex topic.
🧰 Tools
🪛 Markdownlint
150-150: Expected: fenced; Actual: indented
Code block style(MD046, code-block-style)
This adds one additional note about the use of
omitemptywithrequiredfor write-only fields that are in a struct that gets re-used for both a request/response.Fixes #604.
Summary by CodeRabbit