Utoipa 5.0.0 Migration Guide

[juhaku]

Migration Guide 4.x.x -> 5.0.0

Nesting support

All new nesting support is available since utoipa 5.0.0. Nesting needs a path under the api that is going to be nested.
Optionally tags can be provided for all routes of the NestableApi.

This allows better composition and enables users to split a single OpenApi declaration to multiple more reasonable pieces.

#[openapi(
    nest(
        (path = "/path/to/nest/api", api = path::to:NestableApi, tags = [...])
    )
)]

OpenAPI 3.1 only

Since 5.0.0 utoipa will only support OpenAPI 3.1. See more what changes in OpenAPI 3.0 -> OpenAPI 3.1 at
https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0

Enum with discrimiantor

Since 5.0.0 #[serde(tag = ...)] will not be used as a discriminator for enum variants. This is due to nature of inlined schemas
which does not adhere to discrimiantor and causes warnings with certain OpenAPI tooling for client generation. This issue may be revisited in future when assessment of the functionality is mature enough.

Instead utoipa will have all new #[schema(discriminator = ...)] support as demonstrated below. When discriminator is set, it is expected
to schemas to have a field according to the provided value.

More about discriminator https://spec.openapis.org/oas/latest.html#discriminator-object

#[schema(discriminator = "bar_type")]
#[serde(untagged)]
enum BarInternal {
    Baz(BarBarInternal),
    FooBar(FooInternal),
}

// with custom mapping
#[schema(discriminator(property_name = "bar_type", mapping(
    ("bar" = "#/components/schemas/BarBarInternal"),
    ("foo" = "#/components/schemas/FooInternal"),
)))]
#[serde(untagged)]
enum BarInternal {
    Baz(BarBarInternal),
    FooBar(FooInternal),
}

Request bodies and Response bodies content_type

Since 5.0.0 request bodies and response bodies as well as ToRespons and IntoResponses does not support content_type = [...]
array syntax for defining multiple content types. Instead multiple content types need to defined via content attribute found in
request_body and responses response.

 request_body(
    content(
        (Item = "content/type"),
        (Item = "content/type2"),
    )
 )

 responses(
    (status = 200, 
       content(
            (Item = "content/type"),
            (Item = "content/type2"),
        )
    )
 )

Schemas auto collection

Since utoipa 5.0.0 schemas implementing ToSchema will get automatically collected recursively to OpenApi from their usage point e.g.
request_body or response definition. As demonstrated below there is no need call #[openapi(components(schemas(Person, ccount)))] anymore but they will be collected via the registered path paths(test_collect_schema).

 #[derive(ToSchema)]
 struct Account {
     id: i32,
 }

 #[derive(ToSchema)]
 struct Person {
     name: String,
     account: Account,
 }

 #[utoipa::path(
     post,
     request_body = Person,
     path = "/test-collect-schemas",
     responses(
         (status = 200, description = "success response")
     ),
 )]
 async fn test_collect_schemas(_body: Person) -> &'static str {
     ""
 }

 #[derive(OpenApi)]
 #[openapi(paths(test_collect_schemas))]
 struct ApiDoc;

Arrays and tuples with prefixItems

In utoipa 5.0.0 the Arrays and namely tuples will not be represented as allOf since it cannot effectively represent a tuple with correct
value types of an array. Instead a new Array is created with prefixItems to define all possible items of an array which adheres to OpenAPI 3.1 specification. See more about prefix items here https://json-schema.org/understanding-json-schema/reference/array#tupleValidation.

#[utoipa::path(..)] with multiple http operation methods

Since utoipa 5.0.0 multiple http operation methods are supported as demonstrated below. This is in addition to the old syntax that works as previously.

 #[utoipa::path(method(head, get), ...)]
 async fn path() {}

Utoipa path changes

Utoipa PathItemType is renamed to HttpMethod to be more descriptive of what it actually is.

Path trait changes

Since 5.0.0 the Path trait has changed to the following.

pub trait Path {
    /// List of HTTP methods this path operation is served at.
    fn methods() -> Vec<openapi::path::HttpMethod>;

    /// The path this operation is served at.
    fn path() -> String;

    /// [`openapi::path::Operation`] describing http operation details such as request bodies,
    /// parameters and responses.
    fn operation() -> openapi::path::Operation;
}

In 4.x.x it was:

pub trait Path {
    fn path() -> String;

    fn path_item(default_tag: Option<&str>) -> openapi::path::PathItem;
}

Real generics support

Since utoipa 5.0.0 the old aliases support has been removed and no longer present. Schemas need to be defined with full type declaration in their usage point as demonstrated below. Types with as = ... will use the as attribute value as a name prefix for the schema in whole OpenAPI thus the possible path declared in request_body or response body will not affect the name of the schema anymore.

#[derive(ToSchema)]
#[schema(as = path::to::Element<T>)]
enum E<T: ToSchema> {
    One(T),
    Many(Vec<T>),
}

#[utoipa::path(
    get,
    path = "/handler",
    request_body = inline(Person<'_, String, Type<i32>>),
    responses(
        (status = OK, body = inline(Page<Person<'_, String, Type<i32>>>)),
        (status = 400, body = Page<Person<'_, String, Type<i32>>>)
    )
)]
async fn handler() {}

#[utoipa::path(
    get,
    path = "/handler",
    request_body = this::path::does::not::affect::to::SchemaName,
)]
async fn handler() {}

In order to support generic arguments all generic arguments need to implement ToSchema. This was not the case in the 4.x.x release which was not so restrictive. However this is necessary to be able to resolve schemas for generic types upon usage. Thus if someone uses a generic argument that does not implement ToSchema it needs to be wrapped with a new type implementing ToSchema or it needs to be implemented to the type directly.

ToSchema changes

In utoipa 5.0.0 the ToSchema syntax has changed to

pub trait ToSchema: PartialSchema {
    fn name() -> Cow<'static, str> {
        // default implementation
    }

    fn schemas(
        schemas: &mut Vec<(
            String,
            utoipa::openapi::RefOr<utoipa::openapi::schema::Schema>,
        )>,
    ) {
        // nothing by default
    }
}

While it used to be following in 4.x.x

pub trait ToSchema<'__s> {
    fn schema() -> (&'__s str, openapi::RefOr<openapi::schema::Schema>);

    fn aliases() -> Vec<(&'__s str, openapi::schema::Schema)> {
        Vec::new()
    }
}

For more changes you may want to browse the utoipa CHANGELOG.md and utoipa-gen CHANGELOG.md.