agama-project / agama / 11458437041

push

github

fix(rust): revamp the OpenAPI specification (#1564)

The `agama-web-server docs` command generates the OpenAPI specification
of Agama's HTTP API. However, the resulting specification is badly
broken 😢. This pull request aims to make the specification usable.

## Refactoring

Apart from being incomplete, the previous implementation had a few
problems.

* The code relies on [OpenApi
proc-macro](https://docs.rs/utoipa/latest/utoipa/derive.OpenApi.html).
This macro requires the data types to implement the [ToSchema
trait](https://docs.rs/utoipa/latest/utoipa/trait.ToSchema.html), and
due to the orphan rule, we cannot implement it for third-party types
(e.g., `IpAddr`, `IpInet`, etc.).
* We did not find a way to add the description of the common APIs (e.g.,
*progress* or *issues*) under each "scope".

For those reasons, we decided to use the builder API, which is pretty
flexible. We also took the chance to split the generation into smaller
pieces, making it easier to maintain.

## Packaging the OpenAPI documentation

Instead of generating the OpenAPI spec at runtime, we can do it at build
time and put the resulting JSON files in a separate package
(`agama-openapi`).

## Generating the `schema.d.ts`

You can generate the API in two simple steps:

```
$ cargo run -p agama-server --bin agama-web-server openapi > openapi.json
$ npx @hey-api/openapi-ts -i openapi.json -o src/client -c axios
```

## To do

* [x] Merging specifications is not the right approach because it does
not detect conflicts (e.g., network and storage devices). Perhaps it
might be a good idea to generate a separate specification for each scope
(e.g., network).
* [x] Add third-party types descriptions.
* [x] Add validation to CI.

## Future work

* Add the DASD API.
* Add the common interfaces (e.g., *progress*, *issues*, etc.)

0 of 92 new or added lines in 10 files covered. (0.0%)

16873 of 23640 relevant lines covered (71.37%)

34.81 hits per line