fix(rust): revamp the OpenAPI specification

[imobachgs]

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. This macro requires the data types to implement the ToSchema trait, 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

• 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).
• Add third-party types descriptions.
• Add validation to CI.

Future work

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

[mvidner]

I love schemas in general 😄 , they enable so many useful things...
And I've been wondering, even before this PR, what our use case for OpenAPI is.

IIUC, the output, saved as schema.d.ts (generated from the CLI output), will let us delete existing client JavaScript/TypeScript code?

[imobachgs]

I love schemas in general 😄 , they enable so many useful things... And I've been wondering, even before this PR, what our use case for OpenAPI is.

IMHO there are two use cases:

1. generate the types for internal consumption,
2. allow 3rd parties to use the specification for their own clients

IIUC, the output, saved as schema.d.ts (generated from the CLI output), will let us delete existing client JavaScript/TypeScript code?

The schema.d.ts was basically an experiment. Instead of generating the clients (which look pretty complex for our use case), I would like to generate only the types. But I am open to talking with the team about it.

Actually, I do not think it would be that hard to build our own generator for our use case.

[imobachgs]

If you want to give it a try, Hey API seems to be a nice alternative:

npx @hey-api/openapi-ts -i openapi.json -o client -c @hey-api/axios

[jreidinger]

great that it is validated 👍 , but does it also find missing piece?

[imobachgs]

Yes, if it is mentioned and not defined, it is found here (most of the problems were like that). About completely forgotten stuff, we might need to try something different (but I do not know what).