ApiKeyValue with description

[lalvesl]

First, thanks for this really really great lib!

I search in the project for this implementation, but i can't found it, then, i open this issue.

I have a suggestion of a small feature.

It has a api for adding descriptions for personalized auths, but this description don't showing in the view.

//example of a custom ApiKeyValue of ApiKey in SecurityScheme
let api_key_value = ApiKeyValue::with_description(
            "Authorization".to_owned(),
            "Token with format `<Hash in sha256 of <api_token>+<random_salt>>.random_salt"
                .to_owned(),
        );

Would it be possible to add another field displaying this description?

[juhaku]

That is merely a visual thing does it show up in the openapi.json?

I changed the todo-actix-web app demo security key to following:

struct SecurityAddon;

impl Modify for SecurityAddon {
    fn modify(&self, openapi: &mut utoipa::openapi::OpenApi) {
        let components = openapi.components.as_mut().unwrap(); // we can unwrap safely since there already is components registered.
        components.add_security_scheme(
            "api_key",
            SecurityScheme::ApiKey(ApiKey::Header(ApiKeyValue::with_description(
                "todo_apikey",
                "this is description", // <-- here added this description
            ))),
        )
    }
}

And it does show up in the Swagger UI when I run the todo actix-web example https://github.com/juhaku/utoipa/tree/master/examples/todo-actix

[juhaku]

First, thanks for this really really great lib!

Thanks :heart:

[lalvesl]

I'm so sorry... I try here into todo-actix example and it does show up. I try in my application and doesn't show up, but i found the mistake (i put "\<token>" and the markdown need to close of this tag).

let api_key =
            ApiKeyValue::with_description("Authorization".to_owned(), "<token>".to_owned());

I make a checkout for the old version in my application and show up too. I was commit a mistake in my code during my tests, sorry.

About the example of todo_actix, I implemented little different of todo_actix example,

├── server
│   ├── auth.rs
│   ├── mod.rs
│   ├── service.rs
│   └── utility
│       ├── mail
│       │   ├── mod.rs
│       │   ├── send.rs
│       │   └── types.rs
│       └── mod.rs

In each module expose using your scope method with configure only the services of this module recursively, and for implement the authorization method:

 let (app, mut api) = App::new()
    .into_utoipa_app()
    .map(|app| app.wrap(Logger::default()))
    .service(scope::scope("/api").configure(utility::config))
    .split_for_parts();

let api_key = ApiKeyValue::with_description("Authorization", "Only the token is required.");

let components = api.components.as_mut().unwrap();
components.add_security_scheme("Token", SecurityScheme::ApiKey(ApiKey::Header(api_key)));

api.info = Info::default();
api.info.title = "Some Title".to_owned();
api.info.description = Some("Some description".to_owned());

app.service(SwaggerUi::new("/swagger-ui/{_:.*}").url("/api-docs/openapi.json", api))

Thank you for your disposition!