docs: fix YAML command example #624
Conversation
WalkthroughThe pull request introduces significant enhancements to the documentation for the Service CLI, detailing how to utilize the CLI utility effectively. Key updates include expanded instructions on defining input options, creating CLI instances, and running the service with command-line arguments. Additionally, it clarifies the precedence of command-line arguments, introduces new sections for custom commands, and improves error handling for the OpenAPI command. The codebase also sees the addition of a new method and an update to an existing method's signature in Changes
Assessment against linked issues
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 #624 +/- ##
=======================================
Coverage 92.88% 92.88%
=======================================
Files 22 22
Lines 4834 4834
=======================================
Hits 4490 4490
Misses 299 299
Partials 45 45 ☔ View full report in Codecov by Sentry. |
danielgtaylor
force-pushed
the
update-yaml-cmd-example
branch
from
f070a77 to
fba44fd
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Caution
Inline review comments failed to post. This is likely due to GitHub's limits when posting large numbers of comments.
Actionable comments posted: 1
🧹 Outside diff range and nitpick comments (2)
docs/docs/features/cli.md (2)
138-141: LGTM! Consider adding nullability documentation.The update to use
OpenAPI().YAML()with error handling is good. However, given issue #618, consider adding a note about potential differences between CLI-generated and hosted specs, particularly regarding field nullability representation.Add a note like:
+ // Note: The CLI-generated OpenAPI spec may differ from the hosted spec + // (/openapi.yaml) in terms of field nullability representation and ordering. + // The hosted spec includes additional type metadata processed at runtime.🧰 Tools
🪛 Markdownlint
138-138: Column: 1
Hard tabs(MD010, no-hard-tabs)
139-139: Column: 1
Hard tabs(MD010, no-hard-tabs)
140-140: Column: 1
Hard tabs(MD010, no-hard-tabs)
141-141: Column: 1
Hard tabs(MD010, no-hard-tabs)
147-150: Fix markdown formatting while maintaining valuable compatibility note.The note about
DowngradeYAML()is valuable for compatibility. However, the info block should use fenced style for consistency.Update the formatting to:
!!! info "Note" You can use `api.OpenAPI().DowngradeYAML()` to output OpenAPI 3.0 instead of 3.1 for tools that don't support 3.1 yet.🧰 Tools
🪛 Markdownlint
149-149: Expected: fenced; Actual: indented
Code block style(MD046, code-block-style)
🛑 Comments failed to post (1)
docs/docs/features/cli.md (1)
138-141:
⚠️ Potential issueFix indentation: replace tabs with spaces.
The code block uses hard tabs which should be replaced with spaces for consistent rendering across different markdown viewers.
🧰 Tools
🪛 Markdownlint
138-138: Column: 1
Hard tabs(MD010, no-hard-tabs)
139-139: Column: 1
Hard tabs(MD010, no-hard-tabs)
140-140: Column: 1
Hard tabs(MD010, no-hard-tabs)
141-141: Column: 1
Hard tabs(MD010, no-hard-tabs)
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Outside diff range and nitpick comments (1)
docs/docs/features/cli.md (1)
147-150: Maintain consistent code block style.For better maintainability, use fenced code blocks consistently throughout the documentation.
Update the note's formatting to use fenced code blocks:
-!!! info "Note" - - You can use `api.OpenAPI().DowngradeYAML()` to output OpenAPI 3.0 instead of 3.1 for tools that don't support 3.1 yet. +!!! info "Note" + +```text +You can use `api.OpenAPI().DowngradeYAML()` to output OpenAPI 3.0 instead of 3.1 for tools that don't support 3.1 yet. +```🧰 Tools
🪛 Markdownlint
149-149: 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/cli.md (1 hunks)
🧰 Additional context used
🪛 Markdownlint
docs/docs/features/cli.md
138-138: Column: 1
Hard tabs(MD010, no-hard-tabs)
139-139: Column: 1
Hard tabs(MD010, no-hard-tabs)
140-140: Column: 1
Hard tabs(MD010, no-hard-tabs)
141-141: Column: 1
Hard tabs(MD010, no-hard-tabs)
142-142: Column: 1
Hard tabs(MD010, no-hard-tabs)
143-143: Column: 1
Hard tabs(MD010, no-hard-tabs)
149-149: Expected: fenced; Actual: indented
Code block style(MD046, code-block-style)
🔇 Additional comments (1)
docs/docs/features/cli.md (1)
147-150: LGTM! Helpful compatibility note added.The note about OpenAPI version downgrade is a valuable addition that helps users work with tools that don't yet support OpenAPI 3.1.
🧰 Tools
🪛 Markdownlint
149-149: Expected: fenced; Actual: indented
Code block style(MD046, code-block-style)
This PR updates the example command to use the
OpenAPI().YAML()method which handles serialization to YAML for you without the need of a third-party library and taking into account custom serialization logic.Fixes #618.
Summary by CodeRabbit
New Features
Bug Fixes
Documentation