assay_workflow/api/
openapi.rs

1use axum::http::{header, StatusCode};
2use axum::response::{Html, IntoResponse};
3use axum::routing::get;
4use axum::Router;
5use std::sync::Arc;
6use utoipa::OpenApi;
7
8use crate::api::AppState;
9use crate::store::WorkflowStore;
10
11/// Build the OpenAPI specification for the workflow engine.
12#[derive(OpenApi)]
13#[openapi(
14    info(
15        title = "assay-workflow API",
16        version = "0.1.0",
17        description = "Durable workflow engine with REST+SSE API. Language-agnostic — any HTTP client can start workflows, execute activities, send signals.",
18        license(name = "Apache-2.0"),
19    ),
20    paths(
21        crate::api::workflows::start_workflow,
22        crate::api::workflows::list_workflows,
23        crate::api::workflows::describe_workflow,
24        crate::api::workflows::get_events,
25        crate::api::workflows::send_signal,
26        crate::api::workflows::cancel_workflow,
27        crate::api::workflows::terminate_workflow,
28        crate::api::tasks::register_worker,
29        crate::api::tasks::poll_task,
30        crate::api::tasks::complete_task,
31        crate::api::tasks::fail_task,
32        crate::api::tasks::heartbeat_task,
33        crate::api::tasks::worker_heartbeat,
34        crate::api::schedules::create_schedule,
35        crate::api::schedules::list_schedules,
36        crate::api::schedules::get_schedule,
37        crate::api::schedules::delete_schedule,
38        crate::api::workflows::list_children,
39        crate::api::workflows::continue_as_new,
40        crate::api::workers::list_workers,
41        crate::api::workers::health_check,
42    ),
43    components(schemas(
44        crate::types::WorkflowRecord,
45        crate::types::WorkflowEvent,
46        crate::types::WorkflowActivity,
47        crate::types::WorkflowTimer,
48        crate::types::WorkflowSignal,
49        crate::types::WorkflowSchedule,
50        crate::types::WorkflowWorker,
51        crate::types::WorkflowStatus,
52        crate::types::ActivityStatus,
53        crate::api::workflows::StartWorkflowRequest,
54        crate::api::workflows::WorkflowResponse,
55        crate::api::tasks::RegisterWorkerRequest,
56        crate::api::tasks::RegisterWorkerResponse,
57        crate::api::tasks::PollRequest,
58        crate::api::tasks::CompleteTaskBody,
59        crate::api::tasks::FailTaskBody,
60        crate::api::schedules::CreateScheduleRequest,
61        crate::api::workflows::ContinueAsNewBody,
62    )),
63    tags(
64        (name = "workflows", description = "Workflow lifecycle management"),
65        (name = "tasks", description = "Task execution for worker apps"),
66        (name = "schedules", description = "Cron schedule management"),
67        (name = "workers", description = "Worker registry and health"),
68        (name = "events", description = "Real-time event streams (SSE)"),
69    ),
70    servers(
71        (url = "/", description = "Current server"),
72    ),
73)]
74pub struct ApiDoc;
75
76pub fn router<S: WorkflowStore + 'static>() -> Router<Arc<AppState<S>>> {
77    Router::new()
78        .route("/api/v1/openapi.json", get(openapi_json))
79        .route("/api/v1/docs", get(docs_page))
80}
81
82async fn openapi_json() -> impl IntoResponse {
83    let spec = ApiDoc::openapi().to_json().unwrap_or_default();
84    (
85        StatusCode::OK,
86        [(header::CONTENT_TYPE, "application/json")],
87        spec,
88    )
89}
90
91/// Lightweight API docs page using Scalar (loaded from CDN, ~50KB).
92async fn docs_page() -> Html<String> {
93    let html = r#"<!DOCTYPE html>
94<html>
95<head>
96    <title>assay-workflow API</title>
97    <meta charset="utf-8">
98    <meta name="viewport" content="width=device-width, initial-scale=1">
99</head>
100<body>
101    <script id="api-reference" data-url="/api/v1/openapi.json"></script>
102    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
103</body>
104</html>"#;
105    Html(html.to_string())
106}
assay_workflow/api/openapi.rs

assay_workflow/api/
openapi.rs
