Struct APIRouter

Source

pub struct APIRouter { /* private fields */ }

Expand description

Router for grouping related routes with shared configuration.

APIRouter allows you to organize routes into logical groups with common prefixes, tags, dependencies, and other shared settings.

§Example

let users_router = APIRouter::new()
    .prefix("/users")
    .tags(vec!["users"])
    .get("", list_users)
    .get("/{id}", get_user)
    .post("", create_user);

let items_router = APIRouter::new()
    .prefix("/items")
    .tags(vec!["items"])
    .get("", list_items);

let app = App::builder()
    .include_router(users_router)
    .include_router(items_router)
    .build();

Implementations§

Source §

impl APIRouter

Source

pub fn new() -> Self

Creates a new empty router.

Source

pub fn with_prefix(prefix: impl Into<String>) -> Self

Creates a new router with the given prefix.

Source

pub fn prefix(self, prefix: impl Into<String>) -> Self

Sets the URL prefix for all routes.

The prefix is prepended to all route paths when the router is included in an application.

Source

pub fn tags(self, tags: Vec<impl Into<String>>) -> Self

Sets the default tags for all routes.

Tags are used for organizing routes in OpenAPI documentation. Route-specific tags are merged with these router-level tags.

Source

pub fn tag(self, tag: impl Into<String>) -> Self

Adds a single tag to the default tags.

Source

pub fn dependency(self, dep: RouterDependency) -> Self

Adds a dependency that runs before all routes.

Dependencies are executed in the order they are added. If a dependency returns an error response, subsequent dependencies and the route handler are not executed.

Source

pub fn dependencies(self, deps: Vec<RouterDependency>) -> Self

Adds multiple dependencies.

Source

pub fn response(self, status_code: u16, def: ResponseDef) -> Self

Adds a response definition for OpenAPI documentation.

Source

pub fn responses(self, responses: HashMap<u16, ResponseDef>) -> Self

Sets shared response definitions.

Source

pub fn deprecated(self, deprecated: bool) -> Self

Marks all routes as deprecated.

Source

pub fn include_in_schema(self, include: bool) -> Self

Sets whether routes should be included in OpenAPI schema.

Source

pub fn route<H, Fut>( self, path: impl Into<String>, method: Method, handler: H, ) -> Self
where H: Fn(&RequestContext, &mut Request) -> Fut + Send + Sync + 'static, Fut: Future<Output = Response> + Send + 'static,

Adds a route with the given method and path.

Source

pub fn get<H, Fut>(self, path: impl Into<String>, handler: H) -> Self
where H: Fn(&RequestContext, &mut Request) -> Fut + Send + Sync + 'static, Fut: Future<Output = Response> + Send + 'static,

Adds a GET route.

Source

pub fn post<H, Fut>(self, path: impl Into<String>, handler: H) -> Self
where H: Fn(&RequestContext, &mut Request) -> Fut + Send + Sync + 'static, Fut: Future<Output = Response> + Send + 'static,

Adds a POST route.

Source

pub fn put<H, Fut>(self, path: impl Into<String>, handler: H) -> Self
where H: Fn(&RequestContext, &mut Request) -> Fut + Send + Sync + 'static, Fut: Future<Output = Response> + Send + 'static,

Adds a PUT route.

Source

pub fn delete<H, Fut>(self, path: impl Into<String>, handler: H) -> Self
where H: Fn(&RequestContext, &mut Request) -> Fut + Send + Sync + 'static, Fut: Future<Output = Response> + Send + 'static,

Adds a DELETE route.

Source

pub fn patch<H, Fut>(self, path: impl Into<String>, handler: H) -> Self
where H: Fn(&RequestContext, &mut Request) -> Fut + Send + Sync + 'static, Fut: Future<Output = Response> + Send + 'static,

Adds a PATCH route.

Source

pub fn options<H, Fut>(self, path: impl Into<String>, handler: H) -> Self
where H: Fn(&RequestContext, &mut Request) -> Fut + Send + Sync + 'static, Fut: Future<Output = Response> + Send + 'static,

Adds an OPTIONS route.

Source

pub fn head<H, Fut>(self, path: impl Into<String>, handler: H) -> Self
where H: Fn(&RequestContext, &mut Request) -> Fut + Send + Sync + 'static, Fut: Future<Output = Response> + Send + 'static,

Adds a HEAD route.

Source

pub fn include_router(self, other: APIRouter) -> Self

Includes another router’s routes with an optional additional prefix.

This allows nesting routers for hierarchical organization.

§Example

let v1_users = APIRouter::new()
    .prefix("/users")
    .get("", list_users);

let v1_router = APIRouter::new()
    .prefix("/v1")
    .include_router(v1_users);

// Routes: /v1/users

Source

pub fn include_router_with_config( self, other: APIRouter, config: IncludeConfig, ) -> Self

Includes another router with configuration overrides.

This allows applying additional configuration when including a router, such as prepending a prefix, adding tags, or injecting dependencies.

§Merge Rules

Following FastAPI’s merge semantics:

prefix: config.prefix + router.prefix + route.path
tags: config.tags + router.tags + route.tags
dependencies: config.deps + router.deps + route.deps
responses: route > router > config (later values win)
deprecated: config overrides router if set
include_in_schema: config overrides router if set

§Example

let users_router = APIRouter::new()
    .prefix("/users")
    .get("", list_users);

let config = IncludeConfig::new()
    .prefix("/api/v1")
    .tags(vec!["api"])
    .dependency(auth_dep);

let app_router = APIRouter::new()
    .include_router_with_config(users_router, config);

// Routes: /api/v1/users with ["api", "users"] tags

Source