Ergonomics when not using macros

[erewok]

Hello! Thanks for building this library: I have been using it in a warp project at work and I wanted to say thanks for working on it!

I also wanted to mention two things I found when working with it.

1. Because I wanted to add a "servers" block in my warp project (and a general lack of enthusiasm about macros), I decided to implement OpenApi directly, something like this:

struct OpenApiDoc;

impl utoipa::OpenApi for OpenApiDoc {
    fn openapi() -> utoipa::openapi::OpenApi {
        let servers = [ServerBuilder::new()
            .url("/api/myapp")
            .description(Some("My API"))
            .build()];

        utoipa::openapi::OpenApiBuilder::new()
            .info(utoipa::openapi::InfoBuilder::new()
                .title("My API")
                .version("version")
                .description(Some("A Rust/Warp application for for work"))
                .contact(
                    Some(utoipa::openapi::ContactBuilder::new()
                        .name(Some("authteam"))
                        .email(Some("[email protected]")).build()),
            ).build())
            .servers(Some(servers))
            .paths(openapi_paths())
            .components(Some(openapi_components()))
            .build()
    }
}

Question: Is it possible to add a "servers" block using the OpenApi derive macro? I didn't see this in the docs anywhere.

2. The above actually wasn't so bad once I figured out how to call MyType::component() to generate an array of component specs, but the paths are pretty involved to create. As a result, I made some convenience functions and traits to make it easier to add things that were useful for us. Here's a modified example:

trait JsonRefContent {
    fn json_component_ref(self, ref_name: &str) -> Self;
}

impl JsonRefContent for RequestBodyBuilder {
    fn json_component_ref(self, ref_name: &str) -> RequestBodyBuilder {
        self.content(
            "application/json",
            utoipa::openapi::Content::new(utoipa::openapi::Ref::from_component_name(ref_name)),
        )
    }
}

In this way, I could make a requestBody like this: RequestBodyBuilder::new().json_component_ref("TokenPayload").build()

Questions:

• I noticed there's no from_response_name (openapi allows defined responses inside components) for the Ref struct. Would that be something you would like to add to this project? (I'd be happy to contribute a PR to add this if so and it's welcome.)
• A trait like the one I have in my project may be overly specific for anyone else, but if not maybe it's something worth adding as well? I'm not sure if this makes sense but figured I'd mention it: it seems pretty specific to the fact that I'm primarily documenting JSON APIs. Still, it did shorten the boilerplate for me when building Path objects.

Overall, I prefer to build this opeapi spec on request (my schema is infrequently requested) or on application start as opposed to in macros, where I have it building at compile time, but I respect that other people wouldn't want that. At any rate, because of this perspective, I'd like to explore ways to improve the ergonomics of the runtime generation of specs.

Thanks again!

[juhaku]

Great that the library has been useful :)

Is it possible to add a "servers" block using the OpenApi derive macro? I didn't see this in the docs anywhere.

At the moment it is not possible to add servers with OpenApi derive macro. Currently the support for attributes is bit limited to only most necessary ones. Support for servers is definitely something that could be added it just has not been the priority since they can also be added with the Modify trait.

I noticed there's no from_response_name (openapi allows defined responses inside components) for the Ref struct. Would that be something you would like to add to this project? (I'd be happy to contribute a PR to add this if so and it's welcome.)

Features that are general purpose are all wecome PR:s. Yes the OpenAPI spec allows defining responses inside components but currently only schema components are supported. There is ongoing effort in making distinction between response and schema components thus allowing definition of other type of components within OpenAPI. See #215.

A trait like the one I have in my project may be overly specific for anyone else, but if not maybe it's something worth adding as well?

Method like above might be okay to add. And adding most commonly used utilities is not a bad thing. But with it need to be careful so that the api does not become polluted of things that not everybody will use. I'd like to keep the basic api as close as possible to the OpenAPI spec and other stuff would be additional extensions. These extras could be under a feature flag allowing users to decide whether they want to pay for the extras or not.

I'd like to explore ways to improve the ergonomics of the runtime generation of specs.

Sure API improvements are welcome and utility functions like above could be be added as extensions to the original types under a feature flag. As an example below. There could be a new feature flag openapi_extensions which enables *Ext traits for builders and types which will contain useful extensions and useful helpers when buiding api manually. And by this way if not all wants to use these extensions they can deside not to use the feature flag.

# in Cargo.toml
[features]
openapi_extensions = []

#[cfg(feature = "openapi_extensions")]
trait RequestBodyBuilderExt {
    fn json_component_ref(self, ref_name: &str) -> Self;
}

#[cfg(feature = "openapi_extensions")]
impl RequestBodyBuilderExt for RequestBodyBuilder {
    fn json_component_ref(self, ref_name: &str) -> RequestBodyBuilder {
        self.content(
            "application/json",
            utoipa::openapi::Content::new(utoipa::openapi::Ref::from_component_name(ref_name)),
        )
    }
}

[erewok]

That sounds like a nice compromise. I'd be happy to put a PR together for that with some documentation for it as well.

Thanks so much!

[erewok]

Thanks for the feedback @juhaku. I made a PR based on our discussion here. No rush on addressing it, of course, and I am happy to take any feedback or modify it as requested.