OpenAPI manager should be usable by other repos

[davepacheco]

Omicron uses the OpenAPI manager (cargo xtask openapi) to manage OpenAPI documents for all of its Dropshot/Progenitor APIs. The intent was always to make this a separate Rust package so that other repos that use the same workflow (e.g., Propolis, Crucible, Dendrite, Maghemite) can use the same tool. This is going to be essential for automated upgrade because upgrade requires support for multiple versions of most APIs, and this tooling (after #7564) is essential for that.

[davepacheco]

One thing that's a little tricky is that today, the package (openapi-manager) provides a binary (cargo xtask openapi) that's tightly coupled at build-time to the APIs within Omicron. For example: openapi-manager directly depends on dns-server-api so that it can call functions in that package in order to generate the OpenAPI document for the dns-server API.

I think what we want is:

• openapi-manager would become a library crate where you can give it a description of the APIs (a ManagedApis object, in openapi manager should support multiple documents for versioned APIs #7564 terms) and it returns a clap app object (openapi_manager::cmd::dispatch::App in openapi manager should support multiple documents for versioned APIs #7564 terms).
• Consumers have their own binary crate (say, omicron-openapi-manager) that depends on all the API crates within the repo. This crate basically just constructs a ManagedApis object (that would be essentially global, like it is today), uses openapi-manager to get back a clap app object, and then runs it.

The net result is that the functionality is all in openapi-manager: subcommands, their arguments, their help output, etc. so that we get a consistent experience across all repositories using this tool.

[sunshowers]

The net result is that the functionality is all in openapi-manager: subcommands, their arguments, their help output, etc. so that we get a consistent experience across all repositories using this tool.

Yes, this is my desired goal too. I think there should be:

• openapi-manager-types: core types, crates can depend on it
• openapi-manager: clap code
• omicron-openapi-manager: containing just the list of api specs + a main function

[sunshowers]

Done in oxidecomputer/dropshot#1429.

[sunshowers]

This is now out:

• https://github.com/oxidecomputer/dropshot-api-manager
• https://crates.io/crates/dropshot-api-manager

Omicron's being ported over to this in #9058.