Skip to content

Commit

Permalink
Add utoipa_axum bindings
Browse files Browse the repository at this point in the history
This PR adds a new crate `utoipa-axum` which provides bindings between
`axum` and `utoipa`. It aims to blend as much as possible to the
existing philosophy of axum way of registering handlers.

This commit introduces new `OpenApiRouter` what wraps `OpenApi` and axum
`Router` which provides passthrough implementation for most of the axum
Router methods and collects and combines the `OpenApi` from registered
routes. Routes registred only via `routes!()` macro will get added to
the `OpenApi`.

Also this commit introduces `routes!()` macro which collects axum
handlers annotated with `#[utoipa::path()]` attribute macro to single
paths intance which is then provided to the `OpenApiRouter`.

Example of supported sytanx.
```rust
let user_router: OpenApiRouter = OpenApiRouter::new()
    .routes(routes!(search_user))
    .routes(routes!(get_user, post_user, delete_user));
```

Fixes #991
  • Loading branch information
juhaku committed Aug 26, 2024
1 parent 6d092e5 commit 969acbf
Show file tree
Hide file tree
Showing 12 changed files with 192 additions and 342 deletions.
3 changes: 3 additions & 0 deletions .github/workflows/build.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ jobs:
- utoipa-redoc
- utoipa-rapidoc
- utoipa-scalar
- utoipa-axum
fail-fast: true
runs-on: ubuntu-latest

Expand Down Expand Up @@ -62,6 +63,8 @@ jobs:
changes=true
elif [[ "$change" == "utoipa-scalar" && "${{ matrix.crate }}" == "utoipa-scalar" && $changes == false ]]; then
changes=true
elif [[ "$change" == "utoipa-axum" && "${{ matrix.crate }}" == "utoipa-axum" && $changes == false ]]; then
changes=true
fi
done < <(git diff --name-only ${{ github.sha }}~ ${{ github.sha }} | grep .rs | awk -F \/ '{print $1}')
echo "${{ matrix.crate }} changes: $changes"
Expand Down
2 changes: 1 addition & 1 deletion scripts/doc.sh
Original file line number Diff line number Diff line change
Expand Up @@ -3,5 +3,5 @@
# Generate utoipa workspace docs

cargo +nightly doc -Z unstable-options --workspace --no-deps \
--features actix_extras,openapi_extensions,yaml,uuid,ulid,url,non_strict_integers,actix-web,axum,rocket,axum_handler \
--features actix_extras,openapi_extensions,yaml,uuid,ulid,url,non_strict_integers,actix-web,axum,rocket \
--config 'build.rustdocflags = ["--cfg", "doc_cfg"]'
3 changes: 1 addition & 2 deletions scripts/test.sh
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,6 @@ for crate in $crates; do
$CARGO test -p utoipa-gen --test path_derive_rocket --features rocket_extras

$CARGO test -p utoipa-gen --test path_derive_axum_test --features axum_extras
$CARGO test -p utoipa-gen --test path_derive_axum_test --features axum_extras,axum_handler
$CARGO test -p utoipa-gen --test path_derive_auto_into_responses_axum --features axum_extras,utoipa/auto_into_responses
elif [[ "$crate" == "utoipa-swagger-ui" ]]; then
$CARGO test -p utoipa-swagger-ui --features actix-web,rocket,axum
Expand All @@ -33,6 +32,6 @@ for crate in $crates; do
elif [[ "$crate" == "utoipa-scalar" ]]; then
$CARGO test -p utoipa-scalar --features actix-web,rocket,axum
elif [[ "$crate" == "utoipa-axum" ]]; then
$CARGO test -p utoipa-axum
$CARGO test -p utoipa-axum --features debug,utoipa/debug
fi
done
10 changes: 8 additions & 2 deletions utoipa-axum/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,20 @@ categories = ["web-programming"]
authors = ["Juha Kukkonen <juha7kukkonen@gmail.com>"]
rust-version.workspace = true

[features]
debug = []

[dependencies]
axum = { version = "0.7", default-features = false }
once_cell = "1"
utoipa = { version = "5.0.0-alpha.1", path = "../utoipa", default-features = false }
utoipa = { version = "5.0.0-alpha", path = "../utoipa", default-features = false }
async-trait = "0.1"
tower-service = "0.3"
tower-layer = "0.3.2"
paste = "1.0"

[package.metadata.docs.rs]
features = []
rustdoc-args = ["--cfg", "doc_cfg"]

[lints.rust]
unexpected_cfgs = { level = "warn", check-cfg = ['cfg(doc_cfg)'] }
Loading

0 comments on commit 969acbf

Please sign in to comment.