Switch to autogeneration of the specification.

[claymcleod]

Manual editing of the YAML has led to some things that make the OpenAPI specification far less useful than it could otherwise be. For example, when retrieving a tesTask from the GET /task/{id} endpoint, the fields that are returned are dependent on the view query parameter. However, if you look at the definition of the schema for tesTask (which the OpenAPI specification indicates is the only valid response returned from that endpoint), it requires that the executors key is always present. This is actually not the case— in fact, the default behavior of the specification only return the id and state keys within that object.

This, in turn, makes it very difficult to use off the shelf (for example, no libraries that autogenerate bindings using the OpenAPI spec can be used).

For what it's worth, we auto-generated the specification using utoipa during the design of the CCDI Federation API, and it was really a pleasant experience (and also had the side benefit of having a Rust implementation that worked right out of the box). There are probably other ways to do it, just giving an example of where I've done this with success.