Skip to content

Conversation

ranger-ross
Copy link
Contributor

This is an attempt to improve error messages for newcomers.

In the scenario when you forget to derive ToSchema the current error message can be a bit overwhelming if you are new to Rust.

#[derive(Debug, Serialize)] // Missing ToSchema
struct Foo {
    name: String,
}

#[utoipa::path(responses((status = 200, body = Foo)))]
#[get("/")]
async fn hello() -> impl Responder {
    todo!()
}

The current compiler error is

error[E0277]: the trait bound `Foo: ToSchema` is not satisfied
  --> src/main.rs:17:48
   |
17 | #[utoipa::path(responses((status = 200, body = Foo)))]
   |                                                ^^^ the trait `ToSchema` is not implemented for `Foo`
   |
   = help: the following other types implement trait `ToSchema`:
             &'t [T]
             &'t mut [T]
             &str
             ()
             BTreeMap<K, T>
             BTreeSet<K>
             Box<T>
             Cow<'a, T>
           and 26 others

error[E0277]: the trait bound `Foo: PartialSchema` is not satisfied
   --> src/main.rs:17:48
    |
17  | #[utoipa::path(responses((status = 200, body = Foo)))]
    |                                                ^^^ the trait `ComposeSchema` is not implemented for `Foo`
    |
    = help: the following other types implement trait `ComposeSchema`:
              &[T]
              &mut [T]
              &str
              BTreeMap<K, T>
              BTreeSet<K>
              Box<T>
              Cow<'a, T>
              HashMap<K, T, S>
            and 24 others
    = note: required for `Foo` to implement `PartialSchema`
note: required by a bound in `utoipa::ToSchema::name`
   --> /home/rosssullivan/projects/utoipa/utoipa/src/lib.rs:374:21
    |
374 | pub trait ToSchema: PartialSchema {
    |                     ^^^^^^^^^^^^^ required by this bound in `ToSchema::name`
...
405 |     fn name() -> Cow<'static, str> {
    |        ---- required by a bound in this associated function

For more information about this error, try `rustc --explain E0277`.

This is a lot.
I think the compiler trying to recommend other types that impl ToSchema is almost always unhelpful.
It's probably quite rare that someone is passing Foo to the utoipa macro when they should passing a primitive.

Thus I added:

  • diagnostic::on_unimplemented on ToSchema with the recommendation to derive ToSchema
  • diagnostic::do_not_recommend on all of the implmentors of ToSchema, ParitialSchema, and ComposeSchema.

With the changes the compiler error is:

error[E0277]: the trait bound `Foo: ToSchema` is not satisfied
  --> src/main.rs:17:48
   |
17 | #[utoipa::path(responses((status = 200, body = Foo)))]
   |                                                ^^^ the trait `ToSchema` is not implemented for `Foo`
   |
   = note: Consider deriving `ToSchema` on `Foo`

error[E0277]: the trait bound `Foo: PartialSchema` is not satisfied
   --> src/main.rs:17:48
    |
17  | #[utoipa::path(responses((status = 200, body = Foo)))]
    |                                                ^^^ the trait `PartialSchema` is not implemented for `Foo`
    |
note: required by a bound in `utoipa::ToSchema::name`
   --> /home/rosssullivan/projects/utoipa/utoipa/src/lib.rs:375:21
    |
375 | pub trait ToSchema: PartialSchema {
    |                     ^^^^^^^^^^^^^ required by this bound in `ToSchema::name`
...
406 |     fn name() -> Cow<'static, str> {
    |        ---- required by a bound in this associated function

For more information about this error, try `rustc --explain E0277`.

I still find the mention of PartialSchema unneeded but I think there is a way to avoid that.
Regardless, I think this is an improvement.

Note on MSRV: Diagnostic attributes were stabilized in Rust 1.78 and do_not_recommend was added in Rust 1.85.
However the diagnostic namespace allows forward compatibility by ignoring unknown attributes. So the MSRV should only need to be raised to 1.78.

This commit uses the #[diagnostic] attributes to improve error messages.
Specifically for missing ToSchema implmentations.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant