docs: generate OpenAPI specification

agent_api_rest/Cargo.toml

@@ -15,6 +15,7 @@ axum.workspace = true
 axum-auth = "0.7"
 axum-macros = "0.4"
 did_manager.workspace = true
+chrono.workspace = true
 http-api-problem = "0.57"
 hyper = { version = "1.2" }
 identity_core.workspace = true
@@ -31,6 +32,8 @@ tower-http.workspace = true
 tracing.workspace = true
 url.workspace = true
 uuid.workspace = true
+utoipa = { version = "5.2", features = ["axum_extras", "chrono", "uuid", "url", "yaml"] }
+utoipa-scalar = { version = "0.2", features = ["axum"] }
 
 [dev-dependencies]
 agent_event_publisher_http = { path = "../agent_event_publisher_http", features = ["test_utils"] }

agent_api_rest/README.md

@@ -7,13 +7,24 @@ Breaking changes may occur before the API reaches a stable version.
 
 The current version of the REST API is `v0`.
 
-### OpenAPI specification (Swagger UI)
+### OpenAPI specification
+
+> [!NOTE]
+> UniCore uses [Scalar](https://scalar.com) to make its OpenAPI specification interactive. It is served under `/<BASE_PATH>/<API_VERSION>/api-reference` (for example: `/v0/api-reference`). The `openapi.yaml` file can be downloaded there as well. The latest version of the `openapi.yaml` file is also deployed as part of the documentation at https://docs.impierce.com/unicore/api-reference.
+
+#### Generate OpenAPI specification
+
+The `openapi.yaml` file can be generated manually by executing the test `generate_openapi_file()` _(ignored in a regular test run)_.
+
+#### Swagger UI
+
+You can also run a local Swagger UI container to inspect the OpenAPI specification.
 
 ```bash
 docker run --rm -p 9090:8080 -e SWAGGER_JSON=/tmp/openapi.yaml -v $(pwd):/tmp swaggerapi/swagger-ui
 ```
 
-Browse to http://localhost:9090
+Browse to http://localhost:9090.
 
 ### CORS