Skip to main content

yang_base/definition/ui/
demo.rs

1//! 默认 Action 演示页契约:参数来源、单参数与整页 schema 及其 `ActionSpec` 投影。
2
3use super::hints::ActionResponseKind;
4use crate::definition::{ActionSpec, ParamSource};
5use schemars::JsonSchema;
6use serde::Serialize;
7
8/// Action 参数在 HTTP 请求中的来源。
9#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, JsonSchema)]
10#[serde(rename_all = "snake_case")]
11#[non_exhaustive]
12pub enum UiParamSource {
13    /// JSON body。
14    Body,
15    /// Query string。
16    Query,
17    /// Path 参数。
18    Path,
19    /// Header。
20    Header,
21}
22
23impl From<ParamSource> for UiParamSource {
24    fn from(source: ParamSource) -> Self {
25        match source {
26            ParamSource::Body => Self::Body,
27            ParamSource::Query => Self::Query,
28            ParamSource::Path => Self::Path,
29            ParamSource::Header => Self::Header,
30        }
31    }
32}
33
34/// 默认 Action 演示页需要的单个参数契约。
35#[derive(Debug, Clone, PartialEq, Eq, Serialize, JsonSchema)]
36pub struct ActionDemoParamSchema {
37    /// 参数名。
38    pub name: String,
39    /// 参数来源。
40    pub source: UiParamSource,
41    /// 是否必填;path 参数即使定义遗漏,也始终为必填。
42    pub required: bool,
43    /// 用户可见标题。
44    pub title: String,
45    /// 参数帮助说明。
46    pub description: String,
47}
48
49/// 单个 Action 的默认演示页契约。
50#[derive(Debug, Clone, PartialEq, Eq, Serialize, JsonSchema)]
51pub struct ActionDemoSchema {
52    /// 全局唯一 operation id。
53    pub operation_id: String,
54    /// 用户可见标题。
55    pub title: String,
56    /// Action 业务说明。
57    pub description: String,
58    /// 标准大写 HTTP method。
59    pub method: String,
60    /// 已校验的服务端路由模板。
61    pub path: String,
62    /// 参数来源与展示信息。
63    pub params: Vec<ActionDemoParamSchema>,
64    /// Handler Input 的 JSON Schema。
65    pub input_schema: serde_json::Value,
66    /// Handler Output 的 JSON Schema。
67    pub output_schema: serde_json::Value,
68    /// 请求媒体类型。
69    pub request_media_type: crate::definition::ActionMediaType,
70    /// multipart 资源与类型限制;JSON Action 为 `None`。
71    pub multipart: Option<crate::definition::MultipartSpec>,
72    /// 成功响应的展示类别。
73    pub response_kind: ActionResponseKind,
74    /// 是否必须先建立认证身份。
75    pub requires_auth: bool,
76}
77
78impl From<&ActionSpec> for ActionDemoSchema {
79    fn from(action: &ActionSpec) -> Self {
80        let params = action
81            .params
82            .iter()
83            .map(|param| {
84                let name = param.name.to_string();
85                ActionDemoParamSchema {
86                    title: if param.presentation.title.is_empty() {
87                        name.clone()
88                    } else {
89                        param.presentation.title.clone()
90                    },
91                    name,
92                    source: param.source.into(),
93                    required: param.required || param.source == ParamSource::Path,
94                    description: param.presentation.description.clone(),
95                }
96            })
97            .collect();
98        Self {
99            operation_id: action.route.operation_id.clone(),
100            title: action.display_name.clone(),
101            description: action.description.clone(),
102            method: action.route.method.as_str().to_string(),
103            path: action.route.path.clone(),
104            params,
105            input_schema: action.input_schema.clone(),
106            output_schema: action.output_schema.clone(),
107            request_media_type: action.request_media_type,
108            multipart: action.multipart.clone(),
109            response_kind: action.response_kind,
110            requires_auth: !action.is_public,
111        }
112    }
113}