linter requests for summary

[jessfraz]

For example:

https://docs.oxide.computer/api/migrate-an-instance-to-a-different-propolis-server,-possibly-on-a-different-sled.

1. No punctuation, there is a comma, I'm already trimming all the periods off but if you want to parse for that would be nice as well.
2. This should just be "Migrate an instance" like three words the rest can be in the description
3. Can we cap the amount of characters to <20 or 25 even.
4. Some summaries are still missing for example https://docs.oxide.computer/api/instance_disks_attach so some sort of error on that

cc @ahl if you think this is possible

[jessfraz]

im also happy to populate them all if you write the tests

[jessfraz]

also ending with "in a project" is kinda redundant, idk if we should test for that or after I fix them all is it obvious not to do that

[ahl]

Yes that sounds feasible in https://github.com/oxidecomputer/openapi-lint; do we want any wiggle room? For example "Migrate an instance" is already 19 characters for a fairly trivial example. Can I negotiate you up to 50 before it becomes a hard error?

A couple of points about this specific example:

1. Do we expect the summaries to be stable? I would suggest using the operation_id for the stable doc URL.
2. I don't know why this would be an API we'd expose--it seems like an ephemeral change rather than policy, that it could easily be undone as part of a migration due to upgrade/failure/etc., and that it's probably the wrong level for a customer (or even an operator) to interact.

[jessfraz]

Haha yes 50 is fine!

And now I know where the tool lives I can also do it myself ;)

Do we expect the summaries to be stable? I would suggest using the operation_id for the stable doc URL.

This is a fair point, I like the human-ness of the summaries a lot. And stripe pulls it off, granted I have no idea how they are generating their docs but the headings and links are human readable strings. I think we can make them stable if we want since basically its mostly like a human reading of a crud endpoint

I don't know why this would be an API we'd expose--it seems like an ephemeral change rather than policy, that it could easily be undone as part of a migration due to upgrade/failure/etc., and that it's probably the wrong level for a customer (or even an operator) to interact.

yes for sure, for that specific endpoint we likely want it hidden anyways. seems like a disaster waiting to happen but was a good example of a long a one

[jessfraz]

I feel like the operation ID just screams like we generated it versus docs should really be human consumable

[jessfraz]

also ill clean up endpoints we want hidden when I do a sweep, should we require descriptions as well and I can fill them in for any existing. I think for the docs its helpful to have a bit about the endpoint.

[jessfraz]

Also we might consider doing #![deny(missing_docs)]

I did this for the cli since everything is generated from comments as well, and its been so nice!

https://github.com/oxidecomputer/cli/blob/main/src/main.rs#L2`