wae_schema/openapi/
builder.rs

1//! OpenAPI 文档构建器
2//!
3//! 提供流畅的 API 来构建符合 OpenAPI 3.1 规范的文档。
4
5use super::super::*;
6use std::collections::BTreeMap;
7
8/// OpenAPI 文档构建器
9///
10/// 提供流畅的 API 来构建 OpenAPI 文档。
11pub struct OpenApiBuilder {
12    doc: OpenApiDoc,
13}
14
15impl OpenApiBuilder {
16    /// 创建新的 OpenAPI 构建器
17    pub fn new() -> Self {
18        Self { doc: OpenApiDoc::default() }
19    }
20
21    /// 创建指定标题和版本的 OpenAPI 构建器
22    pub fn with_title_and_version(title: impl Into<String>, version: impl Into<String>) -> Self {
23        Self { doc: OpenApiDoc::new(title, version) }
24    }
25
26    /// 设置 API 标题
27    pub fn title(mut self, title: impl Into<String>) -> Self {
28        self.doc.info.title = title.into();
29        self
30    }
31
32    /// 设置 API 版本
33    pub fn version(mut self, version: impl Into<String>) -> Self {
34        self.doc.info.version = version.into();
35        self
36    }
37
38    /// 设置 API 描述
39    pub fn description(mut self, desc: impl Into<String>) -> Self {
40        self.doc.info.description = Some(desc.into());
41        self
42    }
43
44    /// 设置服务条款 URL
45    pub fn terms_of_service(mut self, url: impl Into<String>) -> Self {
46        self.doc.info.terms_of_service = Some(url.into());
47        self
48    }
49
50    /// 设置联系信息
51    pub fn contact(mut self, contact: Contact) -> Self {
52        self.doc.info.contact = Some(contact);
53        self
54    }
55
56    /// 设置许可信息
57    pub fn license(mut self, license: License) -> Self {
58        self.doc.info.license = Some(license);
59        self
60    }
61
62    /// 添加路径
63    pub fn path(mut self, path: impl Into<String>, item: PathItem) -> Self {
64        self.doc.paths.insert(path.into(), item);
65        self
66    }
67
68    /// 添加多个路径
69    pub fn paths(mut self, paths: BTreeMap<String, PathItem>) -> Self {
70        self.doc.paths.extend(paths);
71        self
72    }
73
74    /// 添加 Schema 组件
75    pub fn schema(mut self, name: impl Into<String>, schema: Schema) -> Self {
76        let components = self.doc.components.get_or_insert_with(Components::default);
77        components.schemas.insert(name.into(), schema);
78        self
79    }
80
81    /// 添加多个 Schema 组件
82    pub fn schemas(mut self, schemas: BTreeMap<String, Schema>) -> Self {
83        let components = self.doc.components.get_or_insert_with(Components::default);
84        components.schemas.extend(schemas);
85        self
86    }
87
88    /// 添加响应组件
89    pub fn response(mut self, name: impl Into<String>, response: Response) -> Self {
90        let components = self.doc.components.get_or_insert_with(Components::default);
91        components.responses.insert(name.into(), response);
92        self
93    }
94
95    /// 添加多个响应组件
96    pub fn responses(mut self, responses: BTreeMap<String, Response>) -> Self {
97        let components = self.doc.components.get_or_insert_with(Components::default);
98        components.responses.extend(responses);
99        self
100    }
101
102    /// 添加参数组件
103    pub fn parameter(mut self, name: impl Into<String>, parameter: Parameter) -> Self {
104        let components = self.doc.components.get_or_insert_with(Components::default);
105        components.parameters.insert(name.into(), parameter);
106        self
107    }
108
109    /// 添加多个参数组件
110    pub fn parameters(mut self, parameters: BTreeMap<String, Parameter>) -> Self {
111        let components = self.doc.components.get_or_insert_with(Components::default);
112        components.parameters.extend(parameters);
113        self
114    }
115
116    /// 添加请求体组件
117    pub fn request_body(mut self, name: impl Into<String>, body: RequestBody) -> Self {
118        let components = self.doc.components.get_or_insert_with(Components::default);
119        components.request_bodies.insert(name.into(), body);
120        self
121    }
122
123    /// 添加多个请求体组件
124    pub fn request_bodies(mut self, bodies: BTreeMap<String, RequestBody>) -> Self {
125        let components = self.doc.components.get_or_insert_with(Components::default);
126        components.request_bodies.extend(bodies);
127        self
128    }
129
130    /// 添加安全方案组件
131    pub fn security_scheme(mut self, name: impl Into<String>, scheme: SecurityScheme) -> Self {
132        let components = self.doc.components.get_or_insert_with(Components::default);
133        components.security_schemes.insert(name.into(), scheme);
134        self
135    }
136
137    /// 添加多个安全方案组件
138    pub fn security_schemes(mut self, schemes: BTreeMap<String, SecurityScheme>) -> Self {
139        let components = self.doc.components.get_or_insert_with(Components::default);
140        components.security_schemes.extend(schemes);
141        self
142    }
143
144    /// 添加服务器
145    pub fn server(mut self, url: impl Into<String>, description: Option<String>) -> Self {
146        let servers = self.doc.servers.get_or_insert_with(Vec::new);
147        servers.push(Server { url: url.into(), description, variables: None });
148        self
149    }
150
151    /// 添加多个服务器
152    pub fn servers(mut self, servers: Vec<Server>) -> Self {
153        let doc_servers = self.doc.servers.get_or_insert_with(Vec::new);
154        doc_servers.extend(servers);
155        self
156    }
157
158    /// 添加标签
159    pub fn tag(mut self, name: impl Into<String>, description: Option<String>) -> Self {
160        let tags = self.doc.tags.get_or_insert_with(Vec::new);
161        tags.push(Tag { name: name.into(), description, external_docs: None });
162        self
163    }
164
165    /// 添加多个标签
166    pub fn tags(mut self, tags: Vec<Tag>) -> Self {
167        let doc_tags = self.doc.tags.get_or_insert_with(Vec::new);
168        doc_tags.extend(tags);
169        self
170    }
171
172    /// 设置外部文档
173    pub fn external_docs(mut self, url: impl Into<String>, description: Option<String>) -> Self {
174        self.doc.external_docs = Some(ExternalDocumentation { url: url.into(), description });
175        self
176    }
177
178    /// 添加安全要求
179    pub fn security(mut self, security: SecurityRequirement) -> Self {
180        let securities = self.doc.security.get_or_insert_with(Vec::new);
181        securities.push(security);
182        self
183    }
184
185    /// 添加多个安全要求
186    pub fn securities(mut self, securities: Vec<SecurityRequirement>) -> Self {
187        let doc_securities = self.doc.security.get_or_insert_with(Vec::new);
188        doc_securities.extend(securities);
189        self
190    }
191
192    /// 构建 OpenAPI 文档
193    pub fn build(self) -> OpenApiDoc {
194        self.doc
195    }
196}
197
198impl Default for OpenApiBuilder {
199    /// 创建默认的 OpenAPI 构建器
200    fn default() -> Self {
201        Self::new()
202    }
203}
wae_schema/openapi/builder.rs

wae_schema/openapi/
builder.rs
