• Home
  • Features
  • Pricing
  • Docs
  • Announcements
  • Sign In

agama-project / agama / 11458437041
68%

Build:
DEFAULT BRANCH: master
Ran 22 Oct 2024 10:49AM UTC
Jobs 2
Files 639
Run time 1min
Badge
Embed ▾
README BADGES
x

If you need to use a raster PNG badge, change the '.svg' to '.png' in the link

Markdown

Textile

RDoc

HTML

Rst

22 Oct 2024 10:38AM UTC coverage: 71.375% (-0.3%) from 71.629%
11458437041

push

github

web-flow
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%)

2 existing lines in 2 files now uncovered.

16873 of 23640 relevant lines covered (71.37%)

34.81 hits per line

New Missed Lines in Diff

Lines Coverage ∆ File
6
0.0
rust/agama-server/src/web/docs/l10n.rs
6
0.0
rust/agama-server/src/web/docs/manager.rs
6
0.0
rust/agama-server/src/web/docs/misc.rs
6
0.0
rust/agama-server/src/web/docs/questions.rs
6
0.0
rust/agama-server/src/web/docs/software.rs
6
0.0
rust/agama-server/src/web/docs/storage.rs
8
0.0
rust/agama-server/src/web/docs/users.rs
9
0.0
rust/agama-server/src/web/docs.rs
18
0.0
rust/agama-server/src/web/docs/network.rs
21
0.0
0.0% rust/xtask/src/main.rs

Uncovered Existing Lines

Lines Coverage ∆ File
1
0.0
0.0% rust/agama-server/src/agama-web-server.rs
1
0.0
0.0% rust/xtask/src/main.rs
Subprojects
ID Flag name Job ID Ran Files Coverage
2 rust 11458437041.2 22 Oct 2024 10:49AM UTC 121
25.27
GitHub Action Run
2 service 11403686461.2 18 Oct 2024 12:30PM UTC 518
89.17
GitHub Action Run
Source Files on build 11458437041
  • Tree
  • List 639
  • Changed 53
  • Source Changed 11
  • Coverage Changed 8
Coverage ∆ File Lines Relevant Covered Missed Hits/Line
  • Back to Repo
  • Github Actions Build #11458437041
  • 653ef750 on github
  • Prev Build on master (#11403686465)
  • Next Build on master (#11460749266)
  • Delete
STATUS · Troubleshooting · Open an Issue · Sales · Support · CAREERS · ENTERPRISE · START FREE · SCHEDULE DEMO
ANNOUNCEMENTS · TWITTER · TOS & SLA · Supported CI Services · What's a CI service? · Automated Testing

© 2026 Coveralls, Inc