DioxusLabs/dioxus · error · syn::Error

Use `api_route` instead of `route` to use OpenAPI options

Error message

Use `api_route` instead of `route` to use OpenAPI options

What it means

Thrown by dioxus-fullstack's route macro expansion (CompiledRoute::from_route, packages/fullstack-macro/src/lib.rs:636). The function was annotated with the plain `#[route(...)]` attribute but its arguments include OpenAPI-only fields (summary, description, id, hidden, tags, security, responses, transform). Those fields are only accepted when the macro runs with aide/OpenAPI support enabled, i.e. via `#[api_route(...)]`. Using `route` with them is a compile error so the OpenAPI metadata is never silently dropped.

Source

Thrown at packages/fullstack-macro/src/lib.rs:637

                    path.push_str(&lit.value());
                    path.push('}');
                }
                PathParam::Static(lit) => path.push_str(&lit.value()),
            }
        }

        Some(path)
    }

    /// Removes the arguments in `route` from `args`, and merges them in the output.
    pub fn from_route(
        mut route: Route,
        function: &ItemFn,
        with_aide: bool,
        method_from_macro: Option<Method>,
    ) -> syn::Result<Self> {
        if !with_aide && route.oapi_options.is_some() {
            return Err(syn::Error::new(
                Span::call_site(),
                "Use `api_route` instead of `route` to use OpenAPI options",
            ));
        } else if with_aide && route.oapi_options.is_none() {
            route.oapi_options = Some(OapiOptions {
                summary: None,
                description: None,
                id: None,
                hidden: None,
                tags: None,
                security: None,
                responses: None,
                transform: None,
            });
        }

        let sig = &function.sig;
        let mut arg_map = sig

View on GitHub (pinned to 393d190a80)

Solutions

1. Change the attribute from `#[route(...)]` to `#[api_route(...)]`, keeping the same arguments (e.g. `#[api_route(GET, "/pets", summary = "List pets")]`).
2. If you do not want OpenAPI docs, delete the OpenAPI fields (summary/description/id/hidden/tags/security/responses/transform) from the `#[route(...)]` attribute.
3. Make sure the `api_route` macro is imported/available (dioxus-fullstack with the axum/server features) so the renamed attribute resolves.

Example fix

// before
#[route(GET, "/pets", summary = "List pets")]
async fn list_pets() -> Json<Vec<Pet>> { ... }

// after
#[api_route(GET, "/pets", summary = "List pets")]
async fn list_pets() -> Json<Vec<Pet>> { ... }

# CI guard: fail if plain #[route(...)] uses OpenAPI-only keys
rg -n '#\[route\([^)]*\b(summary|description|id|hidden|tags|security|responses|transform)\s*=' src/ && \
  { echo 'ERROR: use #[api_route] for OpenAPI options'; exit 1; } || true

When it happens

Trigger: Writing `#[route(GET, "/pets", summary = "List pets")]` (or any of the eight oapi fields inside a `#[route(...)]` attribute) instead of `#[api_route(...)]`. Also happens when copying an `api_route` example into a project where the aide/OpenAPI feature setup expects the `api_route` spelling, or when migrating code from `#[server]` endpoints documented with aide.

Common situations: Copying examples from Dioxus fullstack docs that use OpenAPI annotations while your code uses the plain `route` macro; enabling `dioxus/fullstack` with axum and adding OpenAPI metadata without switching the macro name; upgrading Dioxus versions where the split between `route` and `api_route` was introduced.

Related errors

• path parameter `{}` not found in function arguments
• query parameter `{}` not found in function arguments
• Cannot have multiple query parameters when one is a catch-al
• HTTP method specified both in macro and in attribute
• HTTP method not specified in macro or in attribute

AI-assisted analysis of DioxusLabs/dioxus@393d190a80 (2026-08-16). Data as JSON: /api/errors/cf9c8ccfa9d65988. Report an issue: GitHub.