Repository navigation
docs(api): OpenAPI annotations for the native API (WI-2032, r2) - #257
Merged
Merged
Conversation
`/swagger-ui` was mounted but documented nothing: ApiDoc carried only an
`info(...)` block, so `/api-docs/openapi.json` served empty `paths` and
`components`. AGENTS.md calls `/api/...` a compatibility surface documented
through utoipa, which was vacuous while no handler was annotated.
- Annotate every native handler with `#[utoipa::path]`, grouped by tag:
auth, system, setup, queue, history, statistics, config, servers,
categories, rss, groups, articles and dav.
- Derive `ToSchema` on the request/response and shared model types, with
`#[schema(value_type = String)]` for PathBuf fields. `ApiError` describes
the `{error_kind, human_readable, status}` body the middleware emits.
- Split ApiDoc into the always-present base and a `webdav`-gated DAV part,
merged in a manual `OpenApi` impl, so DAV paths appear only in builds that
serve them.
- Add `apps/rustnzb/tests/openapi_document.rs`: every route from the router
must appear in the document, no extra routes may appear, every operation
carries a tag, summary and response, the shared models are registered, and
every `async fn h_*` in a handler module carries an annotation.
- Enable utoipa's `chrono` feature for the shared config and model schemas.
The SABnzbd compatibility layer keeps its separate contract and is
deliberately outside the document.
Bumps nzb-nntp to 0.2.27 and nzb-web to 0.4.25.
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.
Rebase of #250 onto current
main, superseding it.What this carries
/api/...handler, plusapps/rustnzb/tests/openapi_document.rswhich fails when a handler or route is undocumented.mainmoved underneath the original PR, so this also documents the routes main added since:GET /api/config/backupPOST /api/config/backup/previewPOST /api/config/backup/restoreGET /api/config/schedulePUT /api/config/scheduleVersion bumps
ToSchemais public API on the shared crates, so alongside the merge:nzb-core0.2.22 (main) → 0.2.23 — addsToSchemato the schedule typesnzb-web0.4.24 → 0.4.25nzb-nntp0.2.26 → 0.2.27Verification
cargo fmt --all --checkcargo clippy --workspace --all-targets -- -D warningscargo test --workspacecargo test -p rustnzb --test openapi_document(4/4)The SABnzbd compatibility layer remains deliberately outside the OpenAPI document.
Supersedes #250.