generate openapi summary

[jessfraz]

this will be the first line of the doc comment with the longer description being the rest if it is longer

[jessfraz]

related to oxidecomputer/omicron#535

[ahl]

Rustdoc uses the first line as a summary:

/// This is the summary!
///
/// Here are some more details!

I'd suggest we

1. use the first line as the summary
2. use the rest as the description
3. add a lint to make sure the summary is sufficiently pithy (@jessfraz can you suggest a maximum number of characters?)

Alternatively, we could do something like this:

#[endpoint {
    method = GET,
    path = "/foo",
    summary = "get foos"
}]
/// The foo getter must take a valid foo ID which is derived from the....
async fn blah_blah_blah(

I like that the OpenAPI docs come from the rust docs, but I consent that that's a matter of opinion.

[jessfraz]

yeah i like the first line thing

Basically something like "Get instance" "List all instances", "Update an instance", I would say chars around a 12-20 give or take. Maybe max 20

[jessfraz]

fwiw the first line rust doc comment is how clap works with parsing cli usage/docs as well