Merge pull request #18 from CurtisTechSolutions/feat/openapi-contract

feat: generate OpenAPI from shared Rust types

Author: nosam1998

.github/workflows/ci.yml

@@ -29,6 +29,12 @@ jobs:
           GFA_SQLX_WORK_DIR: ${{ runner.temp }}/gfa-sqlx
       - run: cargo build -p gfa-cli --locked
       - run: python3 .github/scripts/local-server-smoke.py
+      - name: Export generated OpenAPI
+        run: cargo run -p gfa-http --example export-openapi --locked > target/openapi.json
+      - uses: actions/upload-artifact@v4
+        with:
+          name: openapi
+          path: target/openapi.json
       - run: cargo xtask check-deps
       - run: cargo check -p gfa-games --no-default-features --locked
   lint:

.gitignore

@@ -7,3 +7,5 @@ dist/
 .env
 .venv/
 __pycache__/
+
+/schemas/openapi.json

Cargo.lock

@@ -50,6 +50,7 @@ uuid = { version = "1", features = ["v4"] }
 tokio-tungstenite = { version = "0.28", default-features = false, features = ["connect", "handshake"] }
 futures-util = { version = "0.3", features = ["sink"] }
 sha2 = "0.10.9"
+utoipa = { version = "5.4.0", default-features = false, features = ["macros"] }
 
 [workspace.lints.rust]
 unsafe_code = "forbid"

Cargo.toml

@@ -5,14 +5,15 @@ edition.workspace = true
 license.workspace = true
 
 [dependencies]
-gfa-core.workspace = true
-gfa-api-types.workspace = true
+gfa-core = { workspace = true, features = ["openapi"] }
+gfa-api-types = { workspace = true, features = ["openapi"] }
 gfa-service.workspace = true
 axum.workspace = true
 serde.workspace = true
 serde_json.workspace = true
 tokio.workspace = true
 sha2.workspace = true
+utoipa.workspace = true
 
 [dev-dependencies]
 tower.workspace = true

crates/adapters/gfa-http/Cargo.toml

@@ -0,0 +1,5 @@
+//! Export the host's generated OpenAPI contract to standard output.
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    println!("{}", gfa_http::openapi_document(true).to_pretty_json()?);
+    Ok(())
+}

crates/adapters/gfa-http/examples/export-openapi.rs

@@ -4,8 +4,7 @@ use axum::{
     response::{IntoResponse, Response},
     Json,
 };
-use gfa_api_types::ApiError;
-use serde_json::json;
+use gfa_api_types::{ApiError, ErrorResponse};
 
 pub(crate) struct HttpError {
     pub status: StatusCode,
@@ -54,6 +53,6 @@ impl From<JsonRejection> for HttpError {
 
 impl IntoResponse for HttpError {
     fn into_response(self) -> Response {
-        (self.status, Json(json!({ "error": self.error }))).into_response()
+        (self.status, Json(ErrorResponse { error: self.error })).into_response()
     }
 }

crates/adapters/gfa-http/src/error.rs

@@ -4,32 +4,20 @@ use axum::{
     http::{header, HeaderMap, StatusCode},
     response::{IntoResponse, Response},
 };
-use gfa_api_types::{Briefing, InfoDetail};
+use gfa_api_types::{
+    Briefing, GameInfoQuery as GameQuery, InfoFormat as Format, MatchInfoQuery as MatchQuery,
+};
 use gfa_service::GameService;
-use serde::Deserialize;
 use serde_json::Value;
 use sha2::{Digest, Sha256};
 use std::sync::Arc;
 
-#[derive(Clone, Copy, Default, Deserialize)]
-#[serde(rename_all = "snake_case")]
-pub(crate) enum Format {
-    #[default]
-    Json,
-    Markdown,
-}
-
-#[derive(Default, Deserialize)]
-#[serde(deny_unknown_fields)]
-pub(crate) struct GameQuery {
-    #[serde(default)]
-    format: Format,
-    #[serde(default)]
-    detail: InfoDetail,
-    config: Option<String>,
-    seat: Option<u8>,
-}
+#[utoipa::path(
+    get, path = "/v1/games/{game_id}/info", tag = "Briefings",
 
+    params(("game_id" = String, Path, description = "Registered game identifier"),gfa_api_types::GameInfoQuery, ("If-None-Match" = Option<String>, Header, description = "ETag, weak tag, list, or *")),
+    responses((status = 200, description = "Deterministic synthetic briefing", content((Briefing = "application/json"), (String = "text/markdown")), headers(("ETag" = String, description = "SHA-256 of this representation"))), (status = 304, description = "Unchanged; no body"), (status = "default", description = "Structured recoverable error; local access requires a loopback peer and matching Host/Origin.", body = gfa_api_types::ErrorResponse))
+)]
 pub(crate) async fn game_info(
     State(service): State<Arc<GameService>>,
     path: Id,
@@ -99,16 +87,12 @@ pub(crate) fn render(
     Ok(response)
 }
 
-#[derive(Default, Deserialize)]
-#[serde(deny_unknown_fields)]
-pub(crate) struct MatchQuery {
-    #[serde(default)]
-    format: Format,
-    #[serde(default)]
-    detail: InfoDetail,
-    seat: Option<u8>,
-}
+#[utoipa::path(
+    get, path = "/v1/matches/{id}/info", tag = "Briefings",
 
+    params(("id" = String, Path, description = "Match identifier"),gfa_api_types::MatchInfoQuery),
+    responses((status = 200, description = "Live match briefing; never cached", content((Briefing = "application/json"), (String = "text/markdown"))), (status = "default", description = "Structured recoverable error; local access requires a loopback peer and matching Host/Origin.", body = gfa_api_types::ErrorResponse))
+)]
 pub(crate) async fn match_info(
     State(service): State<Arc<GameService>>,
     path: Id,

crates/adapters/gfa-http/src/info.rs

@@ -6,6 +6,8 @@
 mod access;
 mod error;
 mod info;
+mod openapi;
+pub use openapi::openapi_document;
 mod stream;
 
 pub use stream::LiveUpdates;
@@ -26,6 +28,7 @@ use gfa_api_types::{ApiError, CreateMatch, MatchState, MoveRequest, MoveResult,
 use gfa_core::{GameSpec, Viewer};
 use gfa_service::GameService;
 use serde::Deserialize;
+#[cfg(test)]
 use serde_json::{json, Value};
 use std::{net::SocketAddr, sync::Arc};
 
@@ -64,7 +67,18 @@ fn build_router(
             "Bind 127.0.0.1 or ::1, then pass listener.local_addr().",
         ));
     }
+    let document = openapi_document(updates.is_some()).to_json().map_err(|_| {
+        ApiError::new(
+            "INVALID_CONFIG",
+            "API documentation could not be generated",
+            "Check schema derives.",
+        )
+    })?;
     let mut router = Router::new()
+        .route(
+            "/v1/openapi.json",
+            get(openapi::document).layer(axum::Extension(openapi::Document(document))),
+        )
         .route("/healthz", get(health))
         .route("/v1/games", get(games))
         .route("/v1/games/{game_id}", get(game))
@@ -122,14 +136,35 @@ fn id(path: Id) -> Result<String, HttpError> {
         .map_err(|error| HttpError::request(error.body_text()))
 }
 
-async fn health() -> Json<Value> {
-    Json(json!({ "status": "ok", "mode": "local" }))
+#[utoipa::path(
+    get, path = "/healthz", tag = "Health",
+
+
+    responses((status = 200, description = "Successful health response", body = gfa_api_types::Health), (status = "default", description = "Structured recoverable error; local access requires a loopback peer and matching Host/Origin.", body = gfa_api_types::ErrorResponse))
+)]
+async fn health() -> Json<gfa_api_types::Health> {
+    Json(gfa_api_types::Health {
+        status: "ok".into(),
+        mode: "local".into(),
+    })
 }
 
+#[utoipa::path(
+    get, path = "/v1/games", tag = "Games",
+
+
+    responses((status = 200, description = "Successful games response", body = Vec<GameSpec>), (status = "default", description = "Structured recoverable error; local access requires a loopback peer and matching Host/Origin.", body = gfa_api_types::ErrorResponse))
+)]
 async fn games(State(service): State<Arc<GameService>>) -> Json<Vec<GameSpec>> {
     Json(service.list_games())
 }
 
+#[utoipa::path(
+    get, path = "/v1/games/{game_id}", tag = "Games",
+
+    params(("game_id" = String, Path, description = "Registered game identifier")),
+    responses((status = 200, description = "Successful game response", body = GameSpec), (status = "default", description = "Structured recoverable error; local access requires a loopback peer and matching Host/Origin.", body = gfa_api_types::ErrorResponse))
+)]
 async fn game(
     State(service): State<Arc<GameService>>,
     path: Id,
@@ -150,6 +185,12 @@ async fn game(
         })
 }
 
+#[utoipa::path(
+    post, path = "/v1/matches", tag = "Matches",
+    request_body(content = gfa_api_types::CreateMatch, example = json!({"game_id":"tictactoe","seed":42})),
+    params(("seat" = Option<u8>, Query, description = "Zero-based seat; omit for spectator view. Creation and position validation default to seat 0.", minimum = 0, maximum = 255)),
+    responses((status = 201, description = "Successful create response", body = gfa_api_types::CreatedMatch), (status = "default", description = "Structured recoverable error; local access requires a loopback peer and matching Host/Origin.", body = gfa_api_types::ErrorResponse))
+)]
 async fn create(
     State(service): State<Arc<GameService>>,
     query: View,
@@ -161,6 +202,12 @@ async fn create(
     Ok((StatusCode::CREATED, Json(state)).into_response())
 }
 
+#[utoipa::path(
+    get, path = "/v1/matches/{id}/state", tag = "Matches",
+
+    params(("id" = String, Path, description = "Match identifier"),("seat" = Option<u8>, Query, description = "Zero-based seat; omit for spectator view. Creation and position validation default to seat 0.", minimum = 0, maximum = 255)),
+    responses((status = 200, description = "Successful state response", body = MatchState), (status = "default", description = "Structured recoverable error; local access requires a loopback peer and matching Host/Origin.", body = gfa_api_types::ErrorResponse))
+)]
 async fn state(
     State(service): State<Arc<GameService>>,
     path: Id,
@@ -171,17 +218,32 @@ async fn state(
     ))
 }
 
+#[utoipa::path(
+    get, path = "/v1/matches/{id}/legal-actions", tag = "Matches",
+
+    params(("id" = String, Path, description = "Match identifier"),("seat" = Option<u8>, Query, description = "Zero-based seat; omit for spectator view. Creation and position validation default to seat 0.", minimum = 0, maximum = 255)),
+    responses((status = 200, description = "Successful legal actions response", body = gfa_api_types::LegalActions), (status = "default", description = "Structured recoverable error; local access requires a loopback peer and matching Host/Origin.", body = gfa_api_types::ErrorResponse))
+)]
 async fn legal_actions(
     State(service): State<Arc<GameService>>,
     path: Id,
     query: View,
-) -> Result<Json<Value>, HttpError> {
+) -> Result<Json<gfa_api_types::LegalActions>, HttpError> {
     let state = service.get_state(&id(path)?, view(query)?.viewer()).await?;
-    Ok(Json(
-        json!({ "turn": state.turn, "to_act": state.to_act, "legal_actions": state.legal_actions, "action_mask": state.action_mask }),
-    ))
+    Ok(Json(gfa_api_types::LegalActions {
+        turn: state.turn,
+        to_act: state.to_act,
+        legal_actions: state.legal_actions,
+        action_mask: state.action_mask,
+    }))
 }
 
+#[utoipa::path(
+    post, path = "/v1/matches/{id}/actions", tag = "Matches",
+    request_body(content = MoveRequest, example = json!({"seat":0,"turn":0,"action":"r2c2"})),
+    params(("id" = String, Path, description = "Match identifier"),("Idempotency-Key" = Option<String>, Header, description = "1–128 bytes; identical retries return the original result.", min_length = 1, max_length = 128)),
+    responses((status = 200, description = "Successful make move response", body = MoveResult), (status = "default", description = "Structured recoverable error; local access requires a loopback peer and matching Host/Origin.", body = gfa_api_types::ErrorResponse))
+)]
 async fn make_move(
     State(service): State<Arc<GameService>>,
     path: Id,
@@ -206,6 +268,12 @@ async fn make_move(
     Ok(Json(service.make_move(&id, request, key).await?))
 }
 
+#[utoipa::path(
+    get, path = "/v1/matches/{id}/replay", tag = "Matches",
+
+    params(("id" = String, Path, description = "Match identifier"),("seat" = Option<u8>, Query, description = "Zero-based seat; omit for spectator view. Creation and position validation default to seat 0.", minimum = 0, maximum = 255)),
+    responses((status = 200, description = "Successful replay response", body = Replay), (status = "default", description = "Structured recoverable error; local access requires a loopback peer and matching Host/Origin.", body = gfa_api_types::ErrorResponse))
+)]
 async fn replay(
     State(service): State<Arc<GameService>>,
     path: Id,
@@ -239,6 +307,12 @@ async fn method_not_allowed() -> HttpError {
 #[cfg(test)]
 mod tests;
 
+#[utoipa::path(
+    post, path = "/v1/games/{game_id}/positions/validate", tag = "Positions",
+    request_body = gfa_api_types::ValidatePosition,
+    params(("game_id" = String, Path, description = "Registered game identifier"),("seat" = Option<u8>, Query, description = "Zero-based seat; omit for spectator view. Creation and position validation default to seat 0.", minimum = 0, maximum = 255)),
+    responses((status = 200, description = "Successful validate position response", body = gfa_api_types::ValidatedPosition), (status = "default", description = "Structured recoverable error; local access requires a loopback peer and matching Host/Origin.", body = gfa_api_types::ErrorResponse))
+)]
 async fn validate_position(
     State(service): State<Arc<GameService>>,
     path: Id,