Add OpenAPI documenation to axum server using utopia

[AlexMikhalev]

See example
https://github.com/juhaku/utoipa/blob/master/examples/todo-axum/src/main.rs

[AlexMikhalev]

Verification and Validation Report: Issue #8

Date: 2026-03-11
Status: NOT IMPLEMENTED

Findings

This issue (opened 2024-01-07) requests OpenAPI documentation using utoipa for the axum server.

Current State

Requirement	Status
utoipa dependency	NOT MET - Not in Cargo.toml
OpenAPI spec generation	NOT MET - No utoipa attributes
API docs	PARTIAL - Inline Rust docs exist
Swagger UI	NOT MET - No endpoint

Evidence

No utoipa dependency:

$ grep -r "utoipa" terraphim_server/Cargo.toml
No matches found

No utoipa annotations on handlers:

// terraphim_server/src/api.rs
pub(crate) async fn create_document(
    State(app_state): State<AppState>,
    Json(document): Json<Document>,
) -> Result<Json<CreateDocumentResponse>> {
    // No #[utoipa::path()] attribute
}

Prototype Exists (Different Approach)

A prototype using poem_openapi exists in lab/parking-lot/server-poem/, but this uses the poem framework, not axum+utoipa.

Implementation Path

If implementing:

1. Add utoipa and utoipa-swagger-ui to Cargo.toml
2. Add #[derive(ToSchema)] to request/response types
3. Add #[utoipa::path()] attributes to handlers
4. Create #[derive(OpenApi)] spec struct
5. Add Swagger UI route

Estimated effort: 1-2 days

---

Full report: .docs/verification-validation-report-issue-8.md