Struct RustApi 

pub struct RustApi { /* private fields */ }

Main application builder for RustAPI

Example

use rustapi_rs::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    RustApi::new()
        .state(AppState::new())
        .route("/", get(hello))
        .route("/users/{id}", get(get_user))
        .run("127.0.0.1:8080")
        .await
}

Implementations

impl RustApi

pub fn new() -> RustApi

Create a new RustAPI application

pub fn auto() -> RustApi

Create a zero-config RustAPI application.

All routes decorated with #[rustapi::get], #[rustapi::post], etc. are automatically registered. Swagger UI is enabled at /docs by default.

Example

use rustapi_rs::prelude::*;

#[rustapi::get("/users")]
async fn list_users() -> Json<Vec<User>> {
    Json(vec![])
}

#[rustapi::main]
async fn main() -> Result<()> {
    // Zero config - routes are auto-registered!
    RustApi::auto()
        .run("0.0.0.0:8080")
        .await
}

pub fn config() -> RustApiConfig

Create a configurable RustAPI application with auto-routes.

Provides builder methods for customization while still auto-registering all decorated routes.

Example

use rustapi_rs::prelude::*;

RustApi::config()
    .docs_path("/api-docs")
    .body_limit(5 * 1024 * 1024)  // 5MB
    .openapi_info("My API", "2.0.0", Some("API Description"))
    .run("0.0.0.0:8080")
    .await?;

pub fn body_limit(self, limit: usize) -> RustApi

Set the global body size limit for request bodies

This protects against denial-of-service attacks via large payloads. The default limit is 1MB (1024 * 1024 bytes).

Arguments

• limit - Maximum body size in bytes

Example

use rustapi_rs::prelude::*;

RustApi::new()
    .body_limit(5 * 1024 * 1024)  // 5MB limit
    .route("/upload", post(upload_handler))
    .run("127.0.0.1:8080")
    .await

pub fn no_body_limit(self) -> RustApi

Disable the body size limit

Warning: This removes protection against large payload attacks. Only use this if you have other mechanisms to limit request sizes.

Example

RustApi::new()
    .no_body_limit()  // Disable body size limit
    .route("/upload", post(upload_handler))

pub fn layer<L>(self, layer: L) -> RustApi

where L: MiddlewareLayer,

Add a middleware layer to the application

Layers are executed in the order they are added (outermost first). The first layer added will be the first to process the request and the last to process the response.

Example

use rustapi_rs::prelude::*;
use rustapi_core::middleware::{RequestIdLayer, TracingLayer};

RustApi::new()
    .layer(RequestIdLayer::new())  // First to process request
    .layer(TracingLayer::new())    // Second to process request
    .route("/", get(handler))
    .run("127.0.0.1:8080")
    .await

pub fn request_interceptor<I>(self, interceptor: I) -> RustApi

where I: RequestInterceptor,

Add a request interceptor to the application

Request interceptors are executed in registration order before the route handler. Each interceptor can modify the request before passing it to the next interceptor or handler.

Example

use rustapi_core::{RustApi, interceptor::RequestInterceptor, Request};

#[derive(Clone)]
struct AddRequestId;

impl RequestInterceptor for AddRequestId {
    fn intercept(&self, mut req: Request) -> Request {
        req.extensions_mut().insert(uuid::Uuid::new_v4());
        req
    }

    fn clone_box(&self) -> Box<dyn RequestInterceptor> {
        Box::new(self.clone())
    }
}

RustApi::new()
    .request_interceptor(AddRequestId)
    .route("/", get(handler))
    .run("127.0.0.1:8080")
    .await

pub fn response_interceptor<I>(self, interceptor: I) -> RustApi

where I: ResponseInterceptor,

Add a response interceptor to the application

Response interceptors are executed in reverse registration order after the route handler completes. Each interceptor can modify the response before passing it to the previous interceptor or client.

Example

use rustapi_core::{RustApi, interceptor::ResponseInterceptor, Response};

#[derive(Clone)]
struct AddServerHeader;

impl ResponseInterceptor for AddServerHeader {
    fn intercept(&self, mut res: Response) -> Response {
        res.headers_mut().insert("X-Server", "RustAPI".parse().unwrap());
        res
    }

    fn clone_box(&self) -> Box<dyn ResponseInterceptor> {
        Box::new(self.clone())
    }
}

RustApi::new()
    .response_interceptor(AddServerHeader)
    .route("/", get(handler))
    .run("127.0.0.1:8080")
    .await

pub fn state<S>(self, _state: S) -> RustApi

where S: Clone + Send + Sync + 'static,

Add application state

State is shared across all handlers and can be extracted using State<T>.

Example

#[derive(Clone)]
struct AppState {
    db: DbPool,
}

RustApi::new()
    .state(AppState::new())

pub fn register_schema<T>(self) -> RustApi

where T: for<'a> ToSchema<'a>,

Register an OpenAPI schema

Example

#[derive(Schema)]
struct User { ... }

RustApi::new()
    .register_schema::<User>()

pub fn openapi_info( self, title: &str, version: &str, description: Option<&str>, ) -> RustApi

Configure OpenAPI info (title, version, description)

pub fn openapi_spec(&self) -> &OpenApiSpec

Get the current OpenAPI spec (for advanced usage/testing).

pub fn route(self, path: &str, method_router: MethodRouter) -> RustApi

Add a route

Example

RustApi::new()
    .route("/", get(index))
    .route("/users", get(list_users).post(create_user))
    .route("/users/{id}", get(get_user).delete(delete_user))

pub fn mount(self, path: &str, method_router: MethodRouter) -> RustApi

👎Deprecated: Use route() directly or mount_route() for macro-based routing

Mount a handler (convenience method)

Alias for .route(path, method_router) for a single handler.

pub fn mount_route(self, route: Route) -> RustApi

Mount a route created with #[rustapi::get], #[rustapi::post], etc.

Example

use rustapi_rs::prelude::*;

#[rustapi::get("/users")]
async fn list_users() -> Json<Vec<User>> {
    Json(vec![])
}

RustApi::new()
    .mount_route(route!(list_users))
    .run("127.0.0.1:8080")
    .await

pub fn nest(self, prefix: &str, router: Router) -> RustApi

Nest a router under a prefix

All routes from the nested router will be registered with the prefix prepended to their paths. OpenAPI operations from the nested router are also propagated to the parent’s OpenAPI spec with prefixed paths.

Example

let api_v1 = Router::new()
    .route("/users", get(list_users));

RustApi::new()
    .nest("/api/v1", api_v1)

pub fn serve_static(self, prefix: &str, root: impl Into<PathBuf>) -> RustApi

Serve static files from a directory

Maps a URL path prefix to a filesystem directory. Requests to paths under the prefix will serve files from the corresponding location in the directory.

Arguments

• prefix - URL path prefix (e.g., “/static”, “/assets”)
• root - Filesystem directory path

Features

• Automatic MIME type detection
• ETag and Last-Modified headers for caching
• Index file serving for directories
• Path traversal prevention

Example

use rustapi_rs::prelude::*;

RustApi::new()
    .serve_static("/assets", "./public")
    .serve_static("/uploads", "./uploads")
    .run("127.0.0.1:8080")
    .await

pub fn serve_static_with_config(self, config: StaticFileConfig) -> RustApi

Serve static files with custom configuration

Example

use rustapi_core::static_files::StaticFileConfig;

let config = StaticFileConfig::new("./public", "/assets")
    .max_age(86400)  // Cache for 1 day
    .fallback("index.html");  // SPA fallback

RustApi::new()
    .serve_static_with_config(config)
    .run("127.0.0.1:8080")
    .await

pub fn docs(self, path: &str) -> RustApi

Enable Swagger UI documentation

This adds two endpoints:

• {path} - Swagger UI interface
• {path}/openapi.json - OpenAPI JSON specification

Important: Call .docs() AFTER registering all routes. The OpenAPI specification is captured at the time .docs() is called, so routes added afterwards will not appear in the documentation.

Example

RustApi::new()
    .route("/users", get(list_users))     // Add routes first
    .route("/posts", get(list_posts))     // Add more routes
    .docs("/docs")  // Then enable docs - captures all routes above
    .run("127.0.0.1:8080")
    .await

For RustApi::auto(), routes are collected before .docs() is called, so this is handled automatically.

pub fn docs_with_info( self, path: &str, title: &str, version: &str, description: Option<&str>, ) -> RustApi

Enable Swagger UI documentation with custom API info

Example

RustApi::new()
    .docs_with_info("/docs", "My API", "2.0.0", Some("API for managing users"))

pub fn docs_with_auth( self, path: &str, username: &str, password: &str, ) -> RustApi

Enable Swagger UI documentation with Basic Auth protection

When username and password are provided, the docs endpoint will require Basic Authentication. This is useful for protecting API documentation in production environments.

Example

RustApi::new()
    .route("/users", get(list_users))
    .docs_with_auth("/docs", "admin", "secret123")
    .run("127.0.0.1:8080")
    .await

pub fn docs_with_auth_and_info( self, path: &str, username: &str, password: &str, title: &str, version: &str, description: Option<&str>, ) -> RustApi

Enable Swagger UI documentation with Basic Auth and custom API info

Example

RustApi::new()
    .docs_with_auth_and_info(
        "/docs",
        "admin",
        "secret",
        "My API",
        "2.0.0",
        Some("Protected API documentation")
    )

pub async fn run(self, addr: &str) -> Result<(), Box<dyn Error + Sync + Send>>

Run the server

Example

RustApi::new()
    .route("/", get(hello))
    .run("127.0.0.1:8080")
    .await

pub fn into_router(self) -> Router

Get the inner router (for testing or advanced usage)

pub fn layers(&self) -> &LayerStack

Get the layer stack (for testing)

pub fn interceptors(&self) -> &InterceptorChain

Get the interceptor chain (for testing)

Trait Implementations

impl Default for RustApi

fn default() -> RustApi

Returns the “default value” for a type.