I have an existing axum webapp, how to add aide?

[matthiasdebernardini]

I don't want to rewrite my app and change all the types and switch to the version of axum that's reexported by aide.

Is there a way to do this? or is this crate not for me?

[JakkuSakura]

You can add docs incrementally by switching to the types "from" aide. They are not re-exports but they are probably compatible with your axum code, if the version matches

[matthiasdebernardini]

I'm adding this in case anyone else needs help and doesn't have the intuition to figure it out immediately like I did.

The answer is;

1. take your existing axum webserver and add a lib.rs and export your route functions and models
2. make a new binary and add aide to it and all the boilerplate found in the examples
3. import your models and routes to the docs server to document it
4. if present, get rid of #[axum::debug_handler] and change the return type of your functions to impl IntoApiResponse
   • this way, you can keep axum as your router and the return types from your functions will be converted properly
5. if you have a Result type wrapped around your IntoApiResponse you'll need to manually unpack the response and turn that into an into_response()
6. if your types in the request payload are not simple you'll need to add a bunch of boiler plate from schemars, just use the String type

This is the resulting route that I got working for one of my existing routes.

        .api_route_with(
            "/api/v1/mint_005_desc",
            post_with(
                |state: State<SirenState>, body: Json<Mint005Keys>| async move {
                    match make_mint005_vault_descriptor(state, body).await {
                        Ok(response) => response.into_response(),
                        Err(err) => err.into_response()
                    }
                },
                |op| {
                    op.summary("Create Vault Descriptor")
                        .description("Creates a descriptor for a vault using the Mint005 template")
                        .tag("Vault Creation")
                        .input::<Json<Mint005Keys>>()
                        .response::<200, Json<Value>>()
                        .response_with::<400, Json<TridentError>, _>(|res| {
                            res.description("Bad request or invalid input")
                        })
                }
            ),
            |p| p.security_requirement("ApiKey"),
        )