Repository navigation
docs(readme): point the validation callout at the single-declaration path - #866
Merged
Merged
Conversation
…path The callout suggests layering @validate_http on the same models next to @openapi, which reads as declaring every model twice. Add one sentence saying @validate_http alone is enough for the spec, with a link to the usage guide. Refs #862 Co-authored-by: sisyphus-dev-ai <sisyphus-dev-ai@users.noreply.github.com>
…the app The zero-duplication section tells readers to call scan_endpoint_metadata(app), although register_openapi_routes and the app= argument of the generators already scan the app. Say so and describe when a direct call is still useful. Refs #862 Co-authored-by: sisyphus-dev-ai <sisyphus-dev-ai@users.noreply.github.com>
There was a problem hiding this comment.
🟢 Approval recommended
No active review issues require changes.
No open issues 🎉
What changed in this PR
Clarifies the single-declaration validation path, addressing #862 without changing runtime behavior or the recommended decorator pairing.
Changes:
- Adds a README signpost explaining that
@validate_httpmetadata can generate the spec without repeating models in@openapi. - Clarifies that route registration and generators using
app=scan metadata automatically, and explains when an explicit scan is useful.
| File | Description |
|---|---|
| README.md | Links the validation callout to the single-declaration usage guide. |
| docs/usage.md | Explains automatic metadata scanning and optional explicit scans. |
Review effort: Balanced
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
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.
Summary
The README validation callout suggests layering
@validate_httpon the same models next to@openapi, which reads as declaring every model twice. This adds the missing signpost for the single-declaration option.Changes
README.md: one sentence appended to the existing callout. It says that@validate_httpalone is enough for the generated spec and links to the usage guide. The callout stays one paragraph and the recommended pairing is unchanged.docs/usage.md: the "Automatic bridge (zero-duplication)" section now says thatregister_openapi_routes(app, ...)and theapp=argument of the generators already scan the app, so a separatescan_endpoint_metadata(app)call is optional, and when a direct call is still useful.Validation
Run locally:
mkdocs build --strict: exit 0 with no new warnings. Theautomatic-bridge-zero-duplicationanchor exists in the built page.@validate_http(body=..., query=..., response_model=..., status_code=201),generate_openapi_spec(app=app)produces the request body, the flattened query parameters, the201response and the422response.GitHub CI on
629de9d: all check runs completed with no failures, including the requiredAnalyze,bandit,ci-required,PR titleandsemgrepcontexts.Related Issues
Closes #862