feat: add utoipa path annotations to all API handlers and wire OpenAPI spec

- Add #[utoipa::path] annotations to all 70+ handler functions across
  auth, config, workflow, and message modules
- Add IntoParams/ToSchema derives to Pagination, PaginatedResponse, ApiResponse
  in erp-core, and MessageQuery/TemplateQuery in erp-message
- Collect all module paths into OpenAPI spec via AuthApiDoc, ConfigApiDoc,
  WorkflowApiDoc, MessageApiDoc structs in erp-server main.rs
- Update openapi_spec handler to merge all module specs
- The /docs/openapi.json endpoint now returns complete API documentation
  with all endpoints, request/response schemas, and security requirements
This commit is contained in:
iven
2026-04-15 01:23:27 +08:00
parent ee65b6e3c9
commit e44d6063be
21 changed files with 1165 additions and 22 deletions

View File

@@ -12,6 +12,18 @@ use crate::dto::{CompleteTaskReq, DelegateTaskReq, TaskResp};
use crate::service::task_service::TaskService;
use crate::workflow_state::WorkflowState;
#[utoipa::path(
get,
path = "/api/v1/workflow/tasks/pending",
params(Pagination),
responses(
(status = 200, description = "成功", body = ApiResponse<PaginatedResponse<TaskResp>>),
(status = 401, description = "未授权"),
(status = 403, description = "权限不足"),
),
security(("bearer_auth" = [])),
tag = "流程任务"
)]
/// GET /api/v1/workflow/tasks/pending
pub async fn list_pending_tasks<S>(
State(state): State<WorkflowState>,
@@ -40,6 +52,18 @@ where
})))
}
#[utoipa::path(
get,
path = "/api/v1/workflow/tasks/completed",
params(Pagination),
responses(
(status = 200, description = "成功", body = ApiResponse<PaginatedResponse<TaskResp>>),
(status = 401, description = "未授权"),
(status = 403, description = "权限不足"),
),
security(("bearer_auth" = [])),
tag = "流程任务"
)]
/// GET /api/v1/workflow/tasks/completed
pub async fn list_completed_tasks<S>(
State(state): State<WorkflowState>,
@@ -68,6 +92,20 @@ where
})))
}
#[utoipa::path(
post,
path = "/api/v1/workflow/tasks/{id}/complete",
params(("id" = Uuid, Path, description = "任务ID")),
request_body = CompleteTaskReq,
responses(
(status = 200, description = "成功", body = ApiResponse<TaskResp>),
(status = 401, description = "未授权"),
(status = 403, description = "权限不足"),
(status = 404, description = "任务不存在"),
),
security(("bearer_auth" = [])),
tag = "流程任务"
)]
/// POST /api/v1/workflow/tasks/{id}/complete
pub async fn complete_task<S>(
State(state): State<WorkflowState>,
@@ -96,6 +134,20 @@ where
Ok(Json(ApiResponse::ok(resp)))
}
#[utoipa::path(
post,
path = "/api/v1/workflow/tasks/{id}/delegate",
params(("id" = Uuid, Path, description = "任务ID")),
request_body = DelegateTaskReq,
responses(
(status = 200, description = "成功", body = ApiResponse<TaskResp>),
(status = 401, description = "未授权"),
(status = 403, description = "权限不足"),
(status = 404, description = "任务不存在"),
),
security(("bearer_auth" = [])),
tag = "流程任务"
)]
/// POST /api/v1/workflow/tasks/{id}/delegate
pub async fn delegate_task<S>(
State(state): State<WorkflowState>,