Next release 2.0.0

[juhaku]

Heads up 📣

The next release will be quite a biggie. It will introduce breaking changes to various places and new features as well. What will change and is know at this point is listed below with examples. The list is not final and may change whenever there is something new to report. This is to notify users already using the library to prepare for changes that will occur when updating to the next major release.
The list is final since the new version 2.0.0 has been released.

Path params type will be using Pascal case instead of lower case

This applies to all parameter types path, header, cookie, query which will be changed to Path, Header, Cookie, Query. This is to make the type to match to the ParameterIn enum type and allow common parsing logic to be shared in multiple places where ParameterIn can be defined.

Before 2.0.0 parameter type was written all in lowercase as seen below.

#[utoipa::path(
   params(
      ("id" = i64, path, description = "Id parameter")
   )
)]

In 2.0.0 types will be in pascal case.

#[utoipa::path(
   params(
      ("id" = i64, Path, description = "Id parameter")
   )
)]

Actix web IntoParams will not be automatic

Before 2.0.0 IntoParams will automatically expect Path<...> or Query<...> wrapped handler function arguments to have implementation for IntoParams trait.
From 2.0.0 onwards this behaviour will change so that it won't expect Path<...> or Query<...> types to have IntoParams implementation unless type is defined within #[utoipa::path(....params(...) )].

This change is to allow users explicitly state whether they want to use IntoParams with their types or not and to allow users to use combination of IntoParmas and regular tuple style parameters for better control of the parameters.

From 2.0.0 onwards types need to be explisitly defined within params.

#[derive(Deserialize, IntoParmas)]
struct QueryParams {
   field: String
}

#[tuoipa::path(
    params(
        QueryParams
    )
)]
async fn handler(query: Query<QueryParams>) {
    ...
}

ComponentFormat in #[component(...)] accepts variant

Before 2.0.0 ComponentFormat needed to defined as a whole component format enum e.g #[component(format = ComponentFormat::Binary)].
From 2.0.0 onwards format can be defined by giving a specific variant of the ComponentFormat enum. This unifies the api syntax to behave similarly to the ParameterIn and ParameterStyle enums.

Define Binary variant of the ComponentFormat enum.

struct Value {
    #[schema(format = Binary)]
    field: String
}

ComponentFormat will change to SchemaFormat in 2.0.0.

Component derive changes in 2.0.0

From 2.0.0 onwards #[derive(Component)] will be #[derive(ToSchema)]. Change is to follow more closely the OpenAPI spec since actually OpenAPI has many different type of components than schema components one of which are response components.

Also all #[component(...)] attributes will change accordinly as #[schema(...)]

#[derive(ToSchema)]
#[schema(...)]
struct MyValue {
    #[schema(...)]
    field: String
}

Also ComponentFormat will change to SchemaFormat from 2.0.0 onwards same as ComponentType will change to SchemaType.

OpenApi derive changes in 2.0.0

Before 2.0.0 openapi derive supported syntax

#[OpenApi]
#[openapi(
  components(Component1, Component2),
  handlers(path::to::the::handler)
)]

From 2.0.0 onwards the syntax changes to:

#[OpenApi]
#[openapi(
  components(
    schemas(Component1, Component2),
    responses(Response1, Response2),
  ),
  paths(path::to::the::handler)
)]

This change is to make API more consistent with the actual OpenAPI spec. Handlers are behind the scenes OpenAPI path objects. Similarly OpenAPI components are not just schema objects but responses and parameters and many more.

Link to the OpenAPI spec: https://swagger.io/specification/

No more separate Property and PropertyBuilder in 2.0.0

From 2.0.0 onwards the Property type and PropertyBuilder will be removed and Object and ObjectBuilder will provide the Property and PropertyBuilder related functionality. See additional details over here #254. If you are using derives this change does not affect you but if you have manual implementation of types this will be a breaking change for you. But mostly changing PropertyBuilder with ObjectBuilder will do the trick.

Before 2.0.0	After 2.0.0
PropertyBuilder::new().schema_type(SchemaType::String)	ObjectBuilder::new().schema_type(SchemaType::String)
Property::new(SchemaType::String)	Object::with_type(SchemaType::String)

Value type Any is now Object

Before 2.0.0 value_type = Any was used to declare type: object in OpenAPI spec. But from 2.0.0 onwards it is declared with value_type = Object. #256

No more chrono_with_format feature

From 2.0.0 onwards there is no seprate feature flag for chrono_with_format instead there is only one feature flag for chrono which is chrono. This feature flag includes the formats from chrono_with_format feature. This is to simplify things and most of the time formats is wanted to be present in the generated api doc. There is no way to get rid of the additional format from now on but it should not matter since they wont harm anyone while being present.

[mjalajel]

Great! Thanks @juhaku,
Do we have a timeline for the v2.0.0 release? (or at least a v1.2 one?)
I've also seen some good improvements after v1.1, especially with axum and looking forward to using them :)

[juhaku]

Great, there is no accurate timeline for the release. But I'm expecting it to be released by the end of next month pessimistically saying. I was hoping to get it out wihtin this month but at the moment it's hard to say whether it can be achieved. There are couple of points need be addressed within this release before it can be released.

For what comes to 1.2 I'm afraid that it is not possible since there are already breaking changes in master waiting to be released and seprating them for minor release would be more trouble than worth I suppose.

[mjalajel]

I see, makes sense to skip 1.2, will look out for v2 then, good luck with that :)

[juhaku]

Utoipa 2.0.0 has now been released thus making this list above the final. 🥳

[kellpossible]

@juhaku, congratulations on this release, and great migration documentation here!

[juhaku]

@kellpossible thank you sir, big portion of the credits belongs to you too.