Upcoming Release 3.0.0

[juhaku]

Lot has changed since the previous release and it has been quite a while too. But as the saying goes "patience will be rewarded" so it does in this occasion as well hereby the time has come to release utoipa 3.0.0 which includes quite a few improvements all around. Without further ado,here is the list of breaking changes that one should keep in mind.

Changes in utoipa ToSchema trait

Previously the schema function returned only the Schema type.

pub trait ToSchema {
    fn schema() -> openapi::schema::Schema;

In 3.0.0 the schema function return type will return RefOf<Schema> to support $ref schemas in #/components/schemas according to the OpenAPI spec. (It used to be possible in 1.x.x).

Also from 3.0.0 onwards schema function will return a tuple containing the name of the schema and the schema or reference to the schema. Trait also has newly introduced lifetimes to reduce allocations on schema names, but not sure whether that is necesary in this case though.

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

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

No more json crate feature

From 3.0.0 onwards people who have used default-features = false in Cargo.toml to disable json feature might want to change their dependency declaration especially if they have explicitly declared json feature. Declaring json dependency when updating to 3.0.0 will fail to compile. It is removed from the dependencies to simpler code in utoipa and afterall it is necessary for full OpenAPI type definitions and is when OpenAPI is being rendered to JSON.

Components::responses changes to BTreeMap

From 3.0.0 onwards utoipa Components::responses will change to BTreeMap to keep the responses order constant.

Content::examples field type changes

Previously in 2.x.x the examples field only allowed Example types.

pub struct Content {
    pub examples: BTreeMap<String, Example>

From 3.0.0 onwards the examples field will allow RefOr<Example> to allow $ref examples according to the OpenAPI spec.

pub struct Content {
    pub examples: BTreeMap<String, RefOr<Example>>

Changes in utoipa ToResponse trait

Prior in 2.x.x. response function allowed only the Response type with the response name.

pub trait ToResponse {
    fn response() -> (String, openapi::response::Response)

From 3.0.0 onwards the response function return type is RefOr<Response> to allow users to use $ref values in #/components/responses according to the OpenAPI spec.

Also from 3.0.0 onwards the response trait uses lifetimes on names instead of heap allocated values.

pub trait ToResponse<'__r> {
    fn response() -> (&'__r str, openapi::RefOr<openapi::response::Response>);
}

Changes in ComponentsBuilder

From 3.0.0 onwards ComponentsBuilder::response_from_into will be renamed to ComponentsBuilder::response_from.

Removed json_response_ref method from ResponseExt

From 3.0.0 onwards the json_response_ref method is removed from ResponseExt implemented for Response when crate feature openapi_extensions is enabled. It is incorrect and against the OpenAPI spec hence removed.

Renamed json_component_ref method to json_schema_ref

From 3.0.0 onwards the json_component_ref method both on ResponseExt and RequestBodyExt is renamed to json_schema_ref to be consistent with the rest of the utoipa library and to follow better the OpenAPI spec.