improve ergonomics of OpenAPI definition generation

[jclulow]

The current print_openapi() is a little unwieldy; it contains a non-optional argument after a sea of optionals, and even if you intend to provide all of the optionals it's a lot of strings that you have to put in the right order.

A simple call, with no optionals, looks like this today:

api.print_openapi(
    &mut f,
    &"Keeper API".to_string(),
    None,
    None,
    None,
    None,
    None,
    None,
    None,
    &"1.0".to_string(),
)?;

I suspect it'd be better as a struct, like:

api.print_openapi(
    &mut f,
    OpenApiDetails {
        name: "Keeper API".to_string(),
        version: "1.0".to_string(),
        ..Default::default()
    },
)?;

It'd be easier and clearer to then incrementally add additional fields; e.g.,

api.print_openapi(
    &mut f,
    OpenApiDetails {
        name: "Keeper API".to_string(),
        version: "1.0".to_string(),
        license_name: Some("CDDL").to_string(),
        ..Default::default()
    },
)?;

[ahl]

Agreed that this is unwieldy, but I don't like the idea of picking defaults for fields that truly require the caller to specify something e.g. the title or version which are mandated by the spec. I'm inclined to do something like this:

api.print_openapi(
    &mut f,
    OpenApiDetails::new(title, version)
        .license_name("CDDL")
);

... but I'm worried that's not very rusty and would welcome suggestions for how it might be improved.

[jclulow]

That sounds great! The point about defaults for values that need something specified is a good one, and the Default pattern doesn't have a good answer there.

I believe what you're describing is indeed quite idiomatic, and is generally caller the builder pattern. See also std::process::Command or std::fs::OpenOptions.

[jclulow]

Actually even better might be api.printer(name, version).licence(...).description(...).write(stream)?.

[ahl]

Yeah, I'm a pretty big fan of the builder pattern in Java, I just haven't seen employed much in Rust.

Agreed that what I had proposed wouldn't actually work, and that last version looks good.

[jclulow]

I'll take a swing at an implementation?

[ahl]

Feel free or I'm happy to get do it--let me know. I was just looking at this, but it might be overkill / odd for a public interface:

https://crates.io/crates/typed-builder