wae_schema/openapi/
paths.rs

1//! OpenAPI 路径定义
2
3use serde::{Deserialize, Serialize};
4use serde_json;
5
6/// 路径项
7#[derive(Debug, Clone, Serialize, Deserialize)]
8pub struct PathItem {
9    /// GET 操作
10    #[serde(skip_serializing_if = "Option::is_none")]
11    pub get: Option<Operation>,
12    /// POST 操作
13    #[serde(skip_serializing_if = "Option::is_none")]
14    pub post: Option<Operation>,
15    /// PUT 操作
16    #[serde(skip_serializing_if = "Option::is_none")]
17    pub put: Option<Operation>,
18    /// DELETE 操作
19    #[serde(skip_serializing_if = "Option::is_none")]
20    pub delete: Option<Operation>,
21    /// PATCH 操作
22    #[serde(skip_serializing_if = "Option::is_none")]
23    pub patch: Option<Operation>,
24    /// HEAD 操作
25    #[serde(skip_serializing_if = "Option::is_none")]
26    pub head: Option<Operation>,
27    /// OPTIONS 操作
28    #[serde(skip_serializing_if = "Option::is_none")]
29    pub options: Option<Operation>,
30    /// TRACE 操作
31    #[serde(skip_serializing_if = "Option::is_none")]
32    pub trace: Option<Operation>,
33    /// 路径描述
34    #[serde(skip_serializing_if = "Option::is_none")]
35    pub description: Option<String>,
36    /// 路径摘要
37    #[serde(skip_serializing_if = "Option::is_none")]
38    pub summary: Option<String>,
39    /// 路径参数
40    #[serde(skip_serializing_if = "Option::is_none")]
41    pub parameters: Option<Vec<ParameterOrReference>>,
42    /// 服务器列表
43    #[serde(skip_serializing_if = "Option::is_none")]
44    pub servers: Option<Vec<super::Server>>,
45}
46
47impl Default for PathItem {
48    /// 创建默认的路径项
49    fn default() -> Self {
50        Self {
51            get: None,
52            post: None,
53            put: None,
54            delete: None,
55            patch: None,
56            head: None,
57            options: None,
58            trace: None,
59            description: None,
60            summary: None,
61            parameters: None,
62            servers: None,
63        }
64    }
65}
66
67impl PathItem {
68    /// 创建新的路径项
69    pub fn new() -> Self {
70        Self::default()
71    }
72
73    /// 设置 GET 操作
74    pub fn get(mut self, op: Operation) -> Self {
75        self.get = Some(op);
76        self
77    }
78
79    /// 设置 POST 操作
80    pub fn post(mut self, op: Operation) -> Self {
81        self.post = Some(op);
82        self
83    }
84
85    /// 设置 PUT 操作
86    pub fn put(mut self, op: Operation) -> Self {
87        self.put = Some(op);
88        self
89    }
90
91    /// 设置 DELETE 操作
92    pub fn delete(mut self, op: Operation) -> Self {
93        self.delete = Some(op);
94        self
95    }
96
97    /// 设置 PATCH 操作
98    pub fn patch(mut self, op: Operation) -> Self {
99        self.patch = Some(op);
100        self
101    }
102
103    /// 设置 HEAD 操作
104    pub fn head(mut self, op: Operation) -> Self {
105        self.head = Some(op);
106        self
107    }
108
109    /// 设置 OPTIONS 操作
110    pub fn options(mut self, op: Operation) -> Self {
111        self.options = Some(op);
112        self
113    }
114
115    /// 设置 TRACE 操作
116    pub fn trace(mut self, op: Operation) -> Self {
117        self.trace = Some(op);
118        self
119    }
120}
121
122/// 操作定义
123#[derive(Debug, Clone, Serialize, Deserialize)]
124pub struct Operation {
125    /// 操作标签
126    #[serde(skip_serializing_if = "Option::is_none")]
127    pub tags: Option<Vec<String>>,
128    /// 操作摘要
129    #[serde(skip_serializing_if = "Option::is_none")]
130    pub summary: Option<String>,
131    /// 操作描述
132    #[serde(skip_serializing_if = "Option::is_none")]
133    pub description: Option<String>,
134    /// 操作 ID
135    #[serde(skip_serializing_if = "Option::is_none")]
136    pub operation_id: Option<String>,
137    /// 参数列表
138    #[serde(skip_serializing_if = "Option::is_none")]
139    pub parameters: Option<Vec<ParameterOrReference>>,
140    /// 请求体
141    #[serde(skip_serializing_if = "Option::is_none")]
142    pub request_body: Option<super::RequestBodyOrReference>,
143    /// 响应定义
144    pub responses: std::collections::BTreeMap<String, super::ResponseOrReference>,
145    /// 回调定义
146    #[serde(skip_serializing_if = "Option::is_none")]
147    pub callbacks: Option<std::collections::BTreeMap<String, super::Callback>>,
148    /// 弃用标记
149    #[serde(default)]
150    pub deprecated: bool,
151    /// 安全要求
152    #[serde(skip_serializing_if = "Option::is_none")]
153    pub security: Option<Vec<super::SecurityRequirement>>,
154    /// 服务器列表
155    #[serde(skip_serializing_if = "Option::is_none")]
156    pub servers: Option<Vec<super::Server>>,
157    /// 外部文档
158    #[serde(skip_serializing_if = "Option::is_none")]
159    pub external_docs: Option<super::ExternalDocumentation>,
160}
161
162impl Operation {
163    /// 创建新操作
164    pub fn new() -> Self {
165        Self {
166            tags: None,
167            summary: None,
168            description: None,
169            operation_id: None,
170            parameters: None,
171            request_body: None,
172            responses: std::collections::BTreeMap::new(),
173            callbacks: None,
174            deprecated: false,
175            security: None,
176            servers: None,
177            external_docs: None,
178        }
179    }
180
181    /// 设置摘要
182    pub fn summary(mut self, summary: impl Into<String>) -> Self {
183        self.summary = Some(summary.into());
184        self
185    }
186
187    /// 设置描述
188    pub fn description(mut self, desc: impl Into<String>) -> Self {
189        self.description = Some(desc.into());
190        self
191    }
192
193    /// 设置操作 ID
194    pub fn operation_id(mut self, id: impl Into<String>) -> Self {
195        self.operation_id = Some(id.into());
196        self
197    }
198
199    /// 添加标签
200    pub fn tag(mut self, tag: impl Into<String>) -> Self {
201        let tags = self.tags.get_or_insert_with(Vec::new);
202        tags.push(tag.into());
203        self
204    }
205
206    /// 添加参数
207    pub fn parameter(mut self, param: ParameterOrReference) -> Self {
208        let params = self.parameters.get_or_insert_with(Vec::new);
209        params.push(param);
210        self
211    }
212
213    /// 设置请求体
214    pub fn request_body(mut self, body: super::RequestBodyOrReference) -> Self {
215        self.request_body = Some(body);
216        self
217    }
218
219    /// 添加响应
220    pub fn response(mut self, status: impl Into<String>, resp: super::ResponseOrReference) -> Self {
221        self.responses.insert(status.into(), resp);
222        self
223    }
224
225    /// 设置弃用
226    pub fn deprecated(mut self, deprecated: bool) -> Self {
227        self.deprecated = deprecated;
228        self
229    }
230}
231
232impl Default for Operation {
233    /// 创建默认的操作
234    fn default() -> Self {
235        Self::new()
236    }
237}
238
239/// 参数定义
240#[derive(Debug, Clone, Serialize, Deserialize)]
241pub struct Parameter {
242    /// 参数名称
243    pub name: String,
244    /// 参数位置
245    #[serde(rename = "in")]
246    pub location: ParameterLocation,
247    /// 参数描述
248    #[serde(skip_serializing_if = "Option::is_none")]
249    pub description: Option<String>,
250    /// 是否必需
251    #[serde(default)]
252    pub required: bool,
253    /// 参数 Schema
254    #[serde(skip_serializing_if = "Option::is_none")]
255    pub schema: Option<crate::Schema>,
256    /// 是否废弃
257    #[serde(default)]
258    pub deprecated: bool,
259    /// 是否允许空值
260    #[serde(default)]
261    pub allow_empty_value: bool,
262    /// 示例值
263    #[serde(skip_serializing_if = "Option::is_none")]
264    pub example: Option<serde_json::Value>,
265    /// 多个示例
266    #[serde(skip_serializing_if = "Option::is_none")]
267    pub examples: Option<std::collections::BTreeMap<String, super::ExampleOrReference>>,
268}
269
270/// 参数位置
271#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
272#[serde(rename_all = "lowercase")]
273pub enum ParameterLocation {
274    /// 路径参数
275    Path,
276    /// 查询参数
277    Query,
278    /// 请求头参数
279    Header,
280    /// Cookie 参数
281    Cookie,
282}
283
284impl Parameter {
285    /// 创建路径参数
286    pub fn path(name: impl Into<String>) -> Self {
287        Self {
288            name: name.into(),
289            location: ParameterLocation::Path,
290            description: None,
291            required: true,
292            schema: None,
293            deprecated: false,
294            allow_empty_value: false,
295            example: None,
296            examples: None,
297        }
298    }
299
300    /// 创建查询参数
301    pub fn query(name: impl Into<String>) -> Self {
302        Self {
303            name: name.into(),
304            location: ParameterLocation::Query,
305            description: None,
306            required: false,
307            schema: None,
308            deprecated: false,
309            allow_empty_value: false,
310            example: None,
311            examples: None,
312        }
313    }
314
315    /// 创建请求头参数
316    pub fn header(name: impl Into<String>) -> Self {
317        Self {
318            name: name.into(),
319            location: ParameterLocation::Header,
320            description: None,
321            required: false,
322            schema: None,
323            deprecated: false,
324            allow_empty_value: false,
325            example: None,
326            examples: None,
327        }
328    }
329
330    /// 创建 Cookie 参数
331    pub fn cookie(name: impl Into<String>) -> Self {
332        Self {
333            name: name.into(),
334            location: ParameterLocation::Cookie,
335            description: None,
336            required: false,
337            schema: None,
338            deprecated: false,
339            allow_empty_value: false,
340            example: None,
341            examples: None,
342        }
343    }
344
345    /// 设置描述
346    pub fn description(mut self, desc: impl Into<String>) -> Self {
347        self.description = Some(desc.into());
348        self
349    }
350
351    /// 设置必需
352    pub fn required(mut self, required: bool) -> Self {
353        self.required = required;
354        self
355    }
356
357    /// 设置 Schema
358    pub fn schema(mut self, schema: crate::Schema) -> Self {
359        self.schema = Some(schema);
360        self
361    }
362
363    /// 设置废弃
364    pub fn deprecated(mut self, deprecated: bool) -> Self {
365        self.deprecated = deprecated;
366        self
367    }
368
369    /// 设置允许空值
370    pub fn allow_empty_value(mut self, allow: bool) -> Self {
371        self.allow_empty_value = allow;
372        self
373    }
374
375    /// 设置示例值
376    pub fn example(mut self, example: serde_json::Value) -> Self {
377        self.example = Some(example);
378        self
379    }
380}
381
382/// 参数或引用
383#[derive(Debug, Clone, Serialize, Deserialize)]
384#[serde(untagged)]
385pub enum ParameterOrReference {
386    /// 参数对象
387    Parameter(Parameter),
388    /// 引用对象
389    Reference(super::Reference),
390}
wae_schema/openapi/paths.rs

wae_schema/openapi/
paths.rs
