Cannot isolate middleware when using wildcard patterns at the same path prefix

[ThomasVille]

Environment

• actix-web version: 4.11.0
• Rust version: 1.85.0

Problem description

I'm trying to serve both REST API endpoints and Swagger UI documentation at the same path prefix (/api) but with different middleware requirements. However, actix-web's routing behavior with wildcard patterns makes it impossible to properly isolate middleware between these different types of content.

Current limitation

There appears to be no way to achieve this configuration:

• GET /api/items - REST endpoint WITH middleware.
• GET /api/* - Swagger UI WITHOUT middleware.

My current solution

With the following code, the middleware is applied only to the REST endpoint as expected, but Swagger UI is served at a different path prefix, which is not what I want:

1. Run the code below cargo run.
2. Make a request to http://127.0.0.1:8080/docs/: Nothing logged as expected.
3. Make a request to http://127.0.0.1:8080/api/items: Logged as expected.

use actix_web::http::header::ContentType;
use actix_web::{App, HttpResponse, HttpServer, Result, get, middleware::Logger, web};
use std::sync::Arc;
use utoipa::OpenApi;
use utoipa_swagger_ui::{Config, SwaggerUi};

// Mock OpenAPI spec for reproduction
#[derive(OpenApi)]
#[openapi(paths(), components(schemas()))]
struct ApiDoc;

// Mock REST endpoint for reproduction
#[get("/items")]
async fn list_items() -> Result<HttpResponse> {
    println!("list_items called - middleware should have logged this");
    Ok(HttpResponse::Ok().json(vec!["item1", "item2"]))
}

fn configure_api(cfg: &mut web::ServiceConfig) {
    // Boilerplate for SwaggerUI.
    let openapi_json = serde_json::to_string(&ApiDoc::openapi()).unwrap();
    let openapi_data = Arc::new(openapi_json);
    let route = "/openapi.json";
    let config = Config::new([format!("/docs{}", route)]).use_base_layout();
    let swagger_ui = SwaggerUi::new("/{_:.*}").config(config);

    // Wrap my REST endpoint with a middleware.
    let api_scope = web::scope("/api")
        .wrap(Logger::new("API REQUEST: %r - Status: %s - Time: %T"))
        .service(list_items);

    // Define another scope just for Swagger UI.
    let swagger_ui_scope = web::scope("/docs")
        .route(
            route,
            web::get().to(move || {
                let openapi_data = openapi_data.clone();
                async move {
                    HttpResponse::Ok()
                        .content_type(ContentType::json())
                        .body(openapi_data.as_ref().clone())
                }
            }),
        )
        .service(swagger_ui);

    cfg.service(api_scope);
    cfg.service(swagger_ui_scope);
}

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    env_logger::init_from_env(env_logger::Env::new().default_filter_or("info"));

    println!("Starting server...");
    println!("Try these URLs:");
    println!(
        "  http://127.0.0.1:8080/docs                      (should NOT show middleware logs - Swagger UI)"
    );
    println!("  http://127.0.0.1:8080/docs/openapi.json         (should NOT show middleware logs)");
    println!("  http://127.0.0.1:8080/api/items                 (should show middleware logs)");

    HttpServer::new(|| App::new().configure(configure_api))
        .bind("127.0.0.1:8080")?
        .run()
        .await
}

Cargo.toml:

[package]
name = "actix_web_issue"
version = "0.1.0"
edition = "2024"

[dependencies]
actix-web = "4.11.0"
env_logger = "0.11.8"
serde_json = "1.0.140"
utoipa = { version = "5.4.0", features = ["actix_extras"] }
utoipa-swagger-ui = { version = "9.0.2", features = ["actix-web"] }

[[bin]]
name = "actix_web_issue"
path = "main.rs"

Attempted approaches

Approach 1: Different Path Prefixes (Works, but not desired)

// This works but forces different URLs
let api_scope = web::scope("/api")
    .wrap(Logger::new("API REQUEST: %r"))
    .service(list_items);

let docs_scope = web::scope("/docs")  // Different prefix
    .service(SwaggerUi::new("/{_:.*}"));

Result: ✅ Middleware isolation works, but API is at /api/items and docs at /docs/ (different prefixes)

Approach 2: Same Scope, SwaggerUI Last

let api_scope = web::scope("/api")
    .service(list_items)                    // REST endpoints first
    .service(SwaggerUi::new("/{_:.*}"))     // Catch-all last
    .wrap(Logger::new("API REQUEST: %r"));  // Middleware affects everything

Result: ❌ Cannot selectively apply middleware - it affects both REST endpoints AND Swagger UI

Approach 3: Separate Scopes, Same Prefix (Doesn't work)

let api_scope = web::scope("/api")
    .wrap(Logger::new("API REQUEST: %r"))
    .service(list_items);

let docs_scope = web::scope("/api")  // Same prefix
    .service(SwaggerUi::new("/{_:.*}"));

cfg.service(api_scope);
cfg.service(docs_scope);

Result: ❌ One of the scopes is ignored entirely.

Questions

1. Is this a fundamental limitation of actix-web's routing when using wildcard patterns at the same path prefix?
2. Is there a recommended pattern for serving both API endpoints and documentation at the same prefix with different middleware?
3. Are there any configuration options or alternative approaches I'm missing?

Use Case

I want to serve a REST API with authentication middleware alongside Swagger UI documentation, both at /api/*. This is a common pattern for API servers where documentation is co-located with the API itself.

Impact

This limitation forces developers to either:

• Use different path prefixes for API and docs (breaking URL consistency)
• Apply middleware to everything including static documentation
• Implement complex and hard to maintain conditional middleware logic

Existing issues

• I've seen Private & Public route handle with middleWare #3427 but I believe this is a slightly different use-case because I'm using scopes.
• I've seen how to exclude a specific route from middlewares that wrap that scope #3201 but I believe their solution should already work for their use-case, and my question includes a wildcard scope that they don't have.

[harshagarwalnyu]

Yeah, actix-web matches services in the order they are defined, but a wildcard scope often "swallows" everything if you aren't careful. The best way to isolate middleware while keeping the same prefix is to use a guard on the scope that has the middleware.

You can use guard::fn_guard to tell the first scope to only activate if the path is not your Swagger path. If it doesn't match, Actix will fall through to your second scope:

use actix_web::{web, guard, App, middleware::Logger};

App::new()
    // Scope 1: REST API with Middleware
    .service(
        web::scope("/api")
            .guard(guard::fn_guard(|ctx| {
                // Only match if NOT a docs request
                !ctx.path().starts_with("/api/docs")
            }))
            .wrap(Logger::default())
            .route("/items", web::get().to(api_handler))
    )
    // Scope 2: Swagger/Wildcard without Middleware
    .service(
        web::scope("/api")
            .route("/docs/{tail:.*}", web::get().to(swagger_handler))
    )

Alternatively, you can wrap individual resources instead of the entire scope. If you only have a few REST endpoints, this is often simpler:

web::scope("/api")
    .service(
        web::resource("/items")
            .wrap(Logger::default())
            .route(web::get().to(api_handler))
    )
    .route("/docs/{tail:.*}", web::get().to(swagger_handler))

Using the guard approach is usually the cleanest for larger projects because it keeps your middleware logic centralized at the scope level without affecting your static or wildcard routes.