1Add another route to the router.
2
3`path` is a string of path segments separated by `/`. Each segment
4can be either static, a capture, or a wildcard.
5
6`method_router` is the [`MethodRouter`] that should receive the request if the
7path matches `path`. `method_router` will commonly be a handler wrapped in a method
8router like [`get`](crate::routing::get). See [`handler`](crate::handler) for
9more details on handlers.
10
11# Static paths
12
13Examples:
14
15- `/`
16- `/foo`
17- `/users/123`
18
19If the incoming request matches the path exactly the corresponding service will
20be called.
21
22# Captures
23
24Paths can contain segments like `/:key` which matches any single segment and
25will store the value captured at `key`.
26
27Examples:
28
29- `/:key`
30- `/users/:id`
31- `/users/:id/tweets`
32
33Captures can be extracted using [`Path`](crate::extract::Path). See its
34documentation for more details.
35
36It is not possible to create segments that only match some types like numbers or
37regular expression. You must handle that manually in your handlers.
38
39[`MatchedPath`](crate::extract::MatchedPath) can be used to extract the matched
40path rather than the actual path.
41
42# Wildcards
43
44Paths can end in `/*key` which matches all segments and will store the segments
45captured at `key`.
46
47Examples:
48
49- `/*key`
50- `/assets/*path`
51- `/:id/:repo/*tree`
52
53Note that `/*key` doesn't match empty segments. Thus:
54
55- `/*key` doesn't match `/` but does match `/a`, `/a/`, etc.
56- `/x/*key` doesn't match `/x` or `/x/` but does match `/x/a`, `/x/a/`, etc.
57
58Wildcard captures can also be extracted using [`Path`](crate::extract::Path).
59Note that the leading slash is not included, i.e. for the route `/foo/*rest` and
60the path `/foo/bar/baz` the value of `rest` will be `bar/baz`.
61
62# Accepting multiple methods
63
64To accept multiple methods for the same route you can add all handlers at the
65same time:
66
67```rust
68use axum::{Router, routing::{get, delete}, extract::Path};
69
70let app = Router::new().route(
71    "/",
72    get(get_root).post(post_root).delete(delete_root),
73);
74
75async fn get_root() {}
76
77async fn post_root() {}
78
79async fn delete_root() {}
80# async {
81# axum::Server::bind(&"".parse().unwrap()).serve(app.into_make_service()).await.unwrap();
82# };
83```
84
85Or you can add them one by one:
86
87```rust
88# use axum::Router;
89# use axum::routing::{get, post, delete};
90#
91let app = Router::new()
92    .route("/", get(get_root))
93    .route("/", post(post_root))
94    .route("/", delete(delete_root));
95#
96# let _: Router = app;
97# async fn get_root() {}
98# async fn post_root() {}
99# async fn delete_root() {}
100```
101
102# More examples
103
104```rust
105use axum::{Router, routing::{get, delete}, extract::Path};
106
107let app = Router::new()
108    .route("/", get(root))
109    .route("/users", get(list_users).post(create_user))
110    .route("/users/:id", get(show_user))
111    .route("/api/:version/users/:id/action", delete(do_users_action))
112    .route("/assets/*path", get(serve_asset));
113
114async fn root() {}
115
116async fn list_users() {}
117
118async fn create_user() {}
119
120async fn show_user(Path(id): Path<u64>) {}
121
122async fn do_users_action(Path((version, id)): Path<(String, u64)>) {}
123
124async fn serve_asset(Path(path): Path<String>) {}
125# async {
126# axum::Server::bind(&"".parse().unwrap()).serve(app.into_make_service()).await.unwrap();
127# };
128```
129
130# Panics
131
132Panics if the route overlaps with another route:
133
134```rust,should_panic
135use axum::{routing::get, Router};
136
137let app = Router::new()
138    .route("/", get(|| async {}))
139    .route("/", get(|| async {}));
140# async {
141# axum::Server::bind(&"".parse().unwrap()).serve(app.into_make_service()).await.unwrap();
142# };
143```
144
145The static route `/foo` and the dynamic route `/:key` are not considered to
146overlap and `/foo` will take precedence.
147
148Also panics if `path` is empty.
149