feat(api): expose OpenAPI 3.1 document at /openapi.json

crates/studio-api/src/endpoints/api_index.rs

@@ -16,6 +16,7 @@ pub async fn handler() -> impl IntoResponse {
             "service": "scarce-studio",
             "version": env!("CARGO_PKG_VERSION"),
             "endpoints": [
+                { "method": "GET",  "path": "/openapi.json",          "description": "OpenAPI 3.1 description of this surface" },
                 { "method": "GET",  "path": "/api/v1",                "description": "this index" },
                 { "method": "GET",  "path": "/api/v1/schemas/{name}", "description": "JSON Schema of a wire type" },
                 { "method": "POST", "path": "/api/v1/rfqs",           "description": "capture a demand record (schema: rfq)" },

crates/studio-api/src/endpoints/get_openapi.rs

@@ -0,0 +1,16 @@
+//! `GET /openapi.json` — serves the assembled OpenAPI 3.1 document (see
+//! `crate::openapi`). Root-mounted by convention: this is the well-known
+//! discovery surface a payment gateway (or any client) probes first.
+
+use std::sync::Arc;
+
+use axum::{extract::State, http::StatusCode, response::IntoResponse, Json};
+
+use crate::AppState;
+
+pub async fn handler(State(state): State<Arc<AppState>>) -> impl IntoResponse {
+    (
+        StatusCode::OK,
+        Json(crate::openapi::document(&state.public_url)),
+    )
+}

crates/studio-api/src/endpoints/mod.rs

@@ -5,6 +5,7 @@ pub mod accept_quote;
 pub mod api_index;
 pub mod create_quote;
 pub mod create_rfq;
+pub mod get_openapi;
 pub mod get_project;
 pub mod get_quote;
 pub mod get_rfq;

crates/studio-api/src/lib.rs

@@ -18,6 +18,7 @@ use sqlx::SqlitePool;
 use studio_types::{Quote, Rfq};
 
 pub mod endpoints;
+pub mod openapi;
 pub mod web;
 
 /// Buzz Desktop download link the project page offers — the canonical
@@ -72,6 +73,9 @@ pub fn router(state: Arc<AppState>) -> Router {
     // `/api/v1` so the contract can evolve without breaking callers.
     Router::new()
         .route("/healthz", get(healthz))
+        // Unversioned like /healthz: the well-known discovery location a
+        // gateway (or any client) probes first.
+        .route("/openapi.json", get(endpoints::get_openapi::handler))
         .route("/api/v1", get(endpoints::api_index::handler))
         .route(
             "/api/v1/schemas/{name}",