tags high level object generation

[jessfraz]

add the high level tags object where the tag name and description exist, this is not being done currently, related to oxidecomputer/omicron#535

[ahl]

It seems like the .tags top level object only really adds value when the tags are accompanied by the optional description field. I'd suggest we have a method in ApiDescription like addTag(name: String, description: Option<String>, external_docs: Option<String>). In addition it might be useful to protect against typos by adding a method to set the "tag disposition" which would be the cross product of: (any tag name, only specified tag names) x (any number of tags including none, at least one tag, exactly one tag)

@davepacheco how's that strike you?

[davepacheco]

That all makes sense!

Thinking ahead a bit (maybe too far), I expect one would probably centralize the tag configuration. I'm thinking something like:

#[derive(Deserialize)]
struct TagConfig {
    allow_other_tags: bool, // whether to allow endpoints to use tags that aren't part of this config
    endpoint_tag_policy: EndpointTagPolicy,
    tag_definitions: Vec<TagDefinition>,
}

#[derive(Deserialize)]
enum EndpointTagPolicy {
    Whatever,
    AtLeastOne,
    ExactlyOne,
}

#[derive(Deserialize)]
struct TagDefinition {
    name: String,
    description: Option<String>,
    external_docs: Option<String>,
}

Consumers like omicron could have a toml file that deserializes to this, and a function that calls the underlying methods on the ApiDescription.

We can defer all this if it seems like too much ceremony or if you think we might want do this differently.