Replace okapi_operation with utoipa

[tillrohrmann]

The dependency okapi_operation is no longer actively maintained and blocks Restate
from upgrading the schemars dependency. Moreover, it only generates OpenAPI 3.0 specs.

To solve this problem, this commit replaces the okapi_operation dependency with the
more actively maintained utoipa dependency which allows us to generate OpenAPI 3.1.
Moreover, it will allow us to eventually drop the restate-utoipa fork once we upstream
the added changes.

As part of this rework, we added the SQL query endpoint to the OpenAPI documentation
and removed the feature gate.

[slinkydeveloper]

Could you post the admin openapi output here? Will run a few tests to see if it generates something sane :)

[tillrohrmann]

Here is the generated OpenAPI spec: https://gist.github.com/tillrohrmann/e1a4b749242f3b554ef55c3b994c434f

[slinkydeveloper]

@tillrohrmann this test failure is being tracked already? https://github.com/restatedev/restate/actions/runs/20754507824/job/59594780154?pr=4125#step:12:172

[slinkydeveloper]

With the changes i posted here, code generation of the docs works fine and LGTM

[tillrohrmann]

@tillrohrmann this test failure is being tracked already? https://github.com/restatedev/restate/actions/runs/20754507824/job/59594780154?pr=4125#step:12:172

Not yet. Will create the corresponding issue.

The issue is #4152.

[nikrooz]

The GET /services/{service} endpoint returns handlers as an array, but the openapi spec display it as a dictionary

[nikrooz]

I think the new OpenAPI spec for admin api is invalid. it has invalid response key, like 400 Bad Request

[tillrohrmann]

I think the new OpenAPI spec for admin api is invalid. it has invalid response key, like 400 Bad Request

@nikrooz did you try out the latest version of this PR? I've pushed an update to address the issue with the "400 Bad Request". It should now generate "400".

[tillrohrmann]

/services/{service}

You are right. There is

restate/crates/types/src/schema/service.rs

Lines 64 to 65 in 094ec11

	#[serde(with = "serde_with::As::<restate_serde_util::MapAsVec>")]
	pub handlers: HashMap<String, HandlerMetadata>,

which maps the map to a vec. I'll update it.

[tillrohrmann]

The GET /services/{service} endpoint returns handlers as an array, but the openapi spec display it as a dictionary

You are right @nikrooz. There is

restate/crates/types/src/schema/service.rs

Lines 64 to 65 in 094ec11

	#[serde(with = "serde_with::As::<restate_serde_util::MapAsVec>")]
	pub handlers: HashMap<String, HandlerMetadata>,

which maps the map to a vec. I'll update it.