Feature: support extensions in utoipa::path macro

[juliendecharentenay]

Hi,

I am only recently getting into openapi, having used rust for a little while. This project is great - started without any issue and got up and running in a very short amount of time.

I am currently working on an api to be hosted on AWS API Gateway and would like to use the extensions - implemented in #1104 - but by defining them via path macros rather than altering the OpenApi struct after the fact.

I am happy to work on it (actually already started to look at it) - but will need an expert eye on it as I am likely to be missing stuff.

My aim is to extend the path macros to support something like the following:

/// Get item
#[utoipa::path(
    get,
    path = "/item",
    responses(
        (status = 200, description = "Pet found successfully", body = Item),
        (status = NOT_FOUND, description = "Pet was not found")
    ),
   extensions(
     (property = "x-amazon-apigateway-integration", value = json!({ "type": "mock" })),
   ),
)]
async fn get_item() -> Item {
    // ...

Essentially, add an additional path attribute "extensions" that takes a list of individually defined extensions, each with a unique key/property. In a first pass, I would limit the value to a specified json - but maybe later could look at defining these separately to avoid repeat.

Is this something of interest that is not already being tackled elsewhere (or implemented in a way that I was not aware of)?

Is it ok for me to contribute? Is there guidelines to follow when contributing [I am fine with the license side]? I am familiar with github/PR/testing/documentation side but not the specific of this project.

Thanks for reading.

[jcaffey]

This is exactly what I need. 👍

[juliendecharentenay]

I got to a working version locally [in a branch]. Happy to push the branch for discussion - but currently I am not authorized.
There is a couple of usability aspects that I am not sure:

• If the definition of each extension using property and value the right way:

(property = "x-my-extension", value = json!({"key": "value"}))

or is it better to go with the following route (more similar to security):

("x-my-extension" = json!({"key": "value"}))

PS: I have used the first one to date.

• The implementation currently uses the "json!" approach as already implemented (ie utoipa-gen parse_utils::parse_json_token_stream). This trigger the needs for the end user code to have "serde_json" as a dependency [and have a version compatible with utoipa]. Not sure other approach should be supported.

[juhaku]

Great idea, there are people coming into this same case whether it is for adding extensions to the path or to the responses.

Currently it is quite convoluted TBH since it requires you to manually edit the OpenApi either via Modify trait or directly the OpenApi before serving.

I am fine with either one of the approaches, perhaps the second one is better since there are few cases where this kind of style is used thus it would be familiar and would not "break the norm" inside the utoipa. The json!(...) approach is fine, there is a recent PR that actually changed it so that it no longer require an explicit serde_json dependency declaration and instead use the one coming with utoipa itself.

[juhaku]

Related #1255

[theswerd]

Do you have docs on how to do this now?

[juhaku]

@theswerd Nope, there are no docs about it, but regardless of using Modify trait or OpenApi directly the result is the same. E.g. one could write something like this.

let mut api = ApiDoc::openapi();
let path_item = api.paths.paths.get_mut("/endpoint").expect("Paths must have endpoint");
let extensions = path_item.extensions.get_or_insert(Extensions::builder().build());
extensions.insert("x-extension".to_string(), serde_json::json!("value"));

Extensions in docs: https://docs.rs/utoipa/latest/utoipa/openapi/extensions/struct.Extensions.html
Modify in docs: https://docs.rs/utoipa/latest/utoipa/trait.Modify.html