docs: generate OpenAPI specification

Cargo.toml

@@ -18,7 +18,7 @@ edition = "2021"
 rust-version = "1.76.0"
 
 [workspace.dependencies]
-did_manager = { git = "https://git@github.com/impierce/did-manager.git", tag = "v1.0.0-beta.2" }
+did_manager = { git = "https://git@github.com/impierce/did-manager.git", tag = "v1.0.0-beta.3" }
 siopv2 = { git = "https://git@github.com/impierce/openid4vc.git", rev = "23facd4" }
 oid4vci = { git = "https://git@github.com/impierce/openid4vc.git", rev = "23facd4" }
 oid4vc-core = { git = "https://git@github.com/impierce/openid4vc.git", rev = "23facd4" }

agent_api_rest/Cargo.toml

@@ -27,6 +27,17 @@ tracing.workspace = true
 tracing-subscriber.workspace = true
 url.workspace = true
 uuid.workspace = true
+utoipa = { version = "=5.0.0-beta.0", features = ["axum_extras", "yaml"] }
+utoipa-scalar = { version = "=0.2.0-beta.0", features = ["axum"] }
+# TODO: wait for new release that contains PR juhaku/utoipa#1002 (current version `=5.0.0-alpha.1`)
+# utoipa = { git = "https://github.com/juhaku/utoipa.git", rev = "f2a7143", features = [
+#     "axum_extras",
+#     "yaml",
+# ] }
+# # TODO: wait for new release that contains PR juhaku/utoipa#1002 (current version `=5.0.0-alpha.1`)
+# utoipa-scalar = { git = "https://github.com/juhaku/utoipa.git", rev = "f2a7143", features = [
+#     "axum",
+# ] }
 
 [dev-dependencies]
 agent_event_publisher_http = { path = "../agent_event_publisher_http", features = ["test_utils"] }
@@ -35,7 +46,9 @@ agent_issuance = { path = "../agent_issuance", features = ["test_utils"] }
 agent_secret_manager = { path = "../agent_secret_manager", features = ["test_utils"] }
 agent_shared = { path = "../agent_shared", features = ["test_utils"] }
 agent_store = { path = "../agent_store" }
-agent_verification = { path = "../agent_verification", features = ["test_utils"] }
+agent_verification = { path = "../agent_verification", features = [
+    "test_utils",
+] }
 
 futures.workspace = true
 jsonwebtoken.workspace = true

agent_api_rest/README.md

@@ -7,13 +7,20 @@ 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.
+
+#### 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