salvo_oapi/swagger_ui/
config.rs

1use serde::Serialize;
2
3use super::oauth;
4use crate::swagger_ui::Url;
5
6const SWAGGER_STANDALONE_LAYOUT: &str = "StandaloneLayout";
7const SWAGGER_BASE_LAYOUT: &str = "BaseLayout";
8
9/// Object used to alter Swagger UI settings.
10///
11/// Config struct provides [Swagger UI configuration](https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md)
12/// for settings which could be altered with **docker variables**.
13///
14/// # Examples
15///
16/// In simple case create config directly from url that points to the api doc json.
17/// ```rust
18/// # use salvo_oapi::swagger_ui::Config;
19/// let config = Config::from("/api-doc.json");
20/// ```
21///
22/// If there is multiple api docs to serve config can be also directly created with [`Config::new`]
23/// ```rust
24/// # use salvo_oapi::swagger_ui::Config;
25/// let config = Config::new(["/api-docs/openapi1.json", "/api-docs/openapi2.json"]);
26/// ```
27///
28/// Or same as above but more verbose syntax.
29/// ```rust
30/// # use salvo_oapi::swagger_ui::{Config, Url};
31/// let config = Config::new([
32///     Url::new("api1", "/api-docs/openapi1.json"),
33///     Url::new("api2", "/api-docs/openapi2.json")
34/// ]);
35/// ```
36///
37/// With oauth config.
38/// ```rust
39/// # use salvo_oapi::swagger_ui::{Config, oauth};
40/// let config = Config::with_oauth_config(
41///     ["/api-docs/openapi1.json", "/api-docs/openapi2.json"],
42///     oauth::Config::new(),
43/// );
44/// ```
45#[non_exhaustive]
46#[derive(Serialize, Clone, Debug)]
47#[serde(rename_all = "camelCase")]
48pub struct Config<'a> {
49    /// Url to fetch external configuration from.
50    #[serde(skip_serializing_if = "Option::is_none")]
51    pub(crate) config_url: Option<String>,
52
53    /// Id of the DOM element where `Swagger UI` will put it's user interface.
54    #[serde(skip_serializing_if = "Option::is_none")]
55    #[serde(rename = "dom_id")]
56    pub(crate) dom_id: Option<String>,
57
58    /// [`Url`] the Swagger UI is serving.
59    #[serde(skip_serializing_if = "Option::is_none")]
60    pub(crate) url: Option<String>,
61
62    /// Name of the primary url if any.
63    #[serde(skip_serializing_if = "Option::is_none", rename = "urls.primaryName")]
64    pub(crate) urls_primary_name: Option<String>,
65
66    /// [`Url`]s the Swagger UI is serving.
67    #[serde(skip_serializing_if = "Vec::is_empty")]
68    pub(crate) urls: Vec<Url<'a>>,
69
70    /// Enables overriding configuration parameters with url query parameters.
71    #[serde(skip_serializing_if = "Option::is_none")]
72    pub(crate) query_config_enabled: Option<bool>,
73
74    /// Controls whether [deep linking](https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/deep-linking.md)
75    /// is enabled in OpenAPI spec.
76    ///
77    /// Deep linking automatically scrolls and expands UI to given url fragment.
78    #[serde(skip_serializing_if = "Option::is_none")]
79    pub(crate) deep_linking: Option<bool>,
80
81    /// Controls whether operation id is shown in the operation list.
82    #[serde(skip_serializing_if = "Option::is_none")]
83    pub(crate) display_operation_id: Option<bool>,
84
85    /// Default models expansion depth; -1 will completely hide the models.
86    #[serde(skip_serializing_if = "Option::is_none")]
87    pub(crate) default_models_expand_depth: Option<isize>,
88
89    /// Default model expansion depth from model example section.
90    #[serde(skip_serializing_if = "Option::is_none")]
91    pub(crate) default_model_expand_depth: Option<isize>,
92
93    /// Defines how models is show when API is first rendered.
94    #[serde(skip_serializing_if = "Option::is_none")]
95    pub(crate) default_model_rendering: Option<String>,
96
97    /// Define whether request duration in milliseconds is displayed for "Try it out" requests.
98    #[serde(skip_serializing_if = "Option::is_none")]
99    pub(crate) display_request_duration: Option<bool>,
100
101    /// Controls default expansion for operations and tags.
102    #[serde(skip_serializing_if = "Option::is_none")]
103    pub(crate) doc_expansion: Option<String>,
104
105    /// Defines is filtering of tagged operations allowed with edit box in top bar.
106    #[serde(skip_serializing_if = "Option::is_none")]
107    pub(crate) filter: Option<bool>,
108
109    /// Controls how many tagged operations are shown. By default all operations are shown.
110    #[serde(skip_serializing_if = "Option::is_none")]
111    pub(crate) max_displayed_tags: Option<usize>,
112
113    /// Defines whether extensions are shown.
114    #[serde(skip_serializing_if = "Option::is_none")]
115    pub(crate) show_extensions: Option<bool>,
116
117    /// Defines whether common extensions are shown.
118    #[serde(skip_serializing_if = "Option::is_none")]
119    pub(crate) show_common_extensions: Option<bool>,
120
121    /// Defines whether "Try it out" section should be enabled by default.
122    #[serde(skip_serializing_if = "Option::is_none")]
123    pub(crate) try_it_out_enabled: Option<bool>,
124
125    /// Defines whether request snippets section is enabled. If disabled legacy curl snipped
126    /// will be used.
127    #[serde(skip_serializing_if = "Option::is_none")]
128    pub(crate) request_snippets_enabled: Option<bool>,
129
130    /// Oauth redirect url.
131    #[serde(skip_serializing_if = "Option::is_none")]
132    pub(crate) oauth2_redirect_url: Option<String>,
133
134    /// Defines whether request mutated with `requestInterceptor` will be used to produce curl command
135    /// in the UI.
136    #[serde(skip_serializing_if = "Option::is_none")]
137    pub(crate) show_mutated_request: Option<bool>,
138
139    /// Define supported http request submit methods.
140    #[serde(skip_serializing_if = "Option::is_none")]
141    pub(crate) supported_submit_methods: Option<Vec<String>>,
142
143    /// Define validator url which is used to validate the Swagger spec. By default the validator swagger.io's
144    /// online validator is used. Setting this to none will disable spec validation.
145    #[serde(skip_serializing_if = "Option::is_none")]
146    pub(crate) validator_url: Option<String>,
147
148    /// Enables passing credentials to CORS requests as defined
149    /// [fetch standards](https://fetch.spec.whatwg.org/#credentials).
150    #[serde(skip_serializing_if = "Option::is_none")]
151    pub(crate) with_credentials: Option<bool>,
152
153    /// Defines whether authorizations is persisted throughout browser refresh and close.
154    #[serde(skip_serializing_if = "Option::is_none")]
155    pub(crate) persist_authorization: Option<bool>,
156
157    /// [`oauth::Config`] the Swagger UI is using for auth flow.
158    #[serde(skip)]
159    pub(crate) oauth: Option<oauth::Config>,
160
161    /// The layout of Swagger UI uses, default is `"StandaloneLayout"`
162    pub(crate) layout: &'a str,
163}
164
165impl<'a> Config<'a> {
166    fn new_<I: IntoIterator<Item = U>, U: Into<Url<'a>>>(urls: I, oauth_config: Option<oauth::Config>) -> Self {
167        let urls = urls.into_iter().map(Into::into).collect::<Vec<Url<'a>>>();
168        let urls_len = urls.len();
169
170        Self {
171            oauth: oauth_config,
172            ..if urls_len == 1 {
173                Self::new_config_with_single_url(urls)
174            } else {
175                Self::new_config_with_multiple_urls(urls)
176            }
177        }
178    }
179
180    fn new_config_with_multiple_urls(urls: Vec<Url<'a>>) -> Self {
181        let primary_name = urls
182            .iter()
183            .find(|url| url.primary)
184            .map(|url| url.name.as_ref().to_owned());
185
186        Self {
187            urls_primary_name: primary_name,
188            urls: urls
189                .into_iter()
190                .map(|mut url| {
191                    if url.name.is_empty() {
192                        url.name = url.url.clone();
193
194                        url
195                    } else {
196                        url
197                    }
198                })
199                .collect(),
200            ..Default::default()
201        }
202    }
203
204    fn new_config_with_single_url(mut urls: Vec<Url<'a>>) -> Self {
205        let url = urls.get_mut(0).map(std::mem::take).expect("urls should not be empty");
206        let primary_name = if url.primary {
207            Some(url.name.as_ref().to_owned())
208        } else {
209            None
210        };
211
212        Self {
213            urls_primary_name: primary_name,
214            url: if url.name.is_empty() {
215                Some(url.url.as_ref().to_owned())
216            } else {
217                None
218            },
219            urls: if !url.name.is_empty() { vec![url] } else { Vec::new() },
220            ..Default::default()
221        }
222    }
223
224    /// Constructs a new [`Config`] from [`Iterator`] of [`Url`]s.
225    ///
226    /// [`Url`]s provided to the [`Config`] will only change the urls Swagger UI is going to use to
227    /// fetch the API document.
228    ///
229    /// # Examples
230    /// Create new config with 2 api doc urls.
231    /// ```rust
232    /// # use salvo_oapi::swagger_ui::Config;
233    /// let config = Config::new(["/api-docs/openapi1.json", "/api-docs/openapi2.json"]);
234    /// ```
235    pub fn new<I: IntoIterator<Item = U>, U: Into<Url<'a>>>(urls: I) -> Self {
236        Self::new_(urls, None)
237    }
238
239    /// Constructs a new [`Config`] from [`Iterator`] of [`Url`]s.
240    ///
241    /// # Examples
242    /// Create new config with oauth config.
243    /// ```rust
244    /// # use salvo_oapi::swagger_ui::{Config, oauth};
245    /// let config = Config::with_oauth_config(
246    ///     ["/api-docs/openapi1.json", "/api-docs/openapi2.json"],
247    ///     oauth::Config::new(),
248    /// );
249    /// ```
250    pub fn with_oauth_config<I: IntoIterator<Item = U>, U: Into<Url<'a>>>(
251        urls: I,
252        oauth_config: oauth::Config,
253    ) -> Self {
254        Self::new_(urls, Some(oauth_config))
255    }
256
257    /// Add url to fetch external configuration from.
258    ///
259    /// # Examples
260    ///
261    /// Set external config url.
262    /// ```rust
263    /// # use salvo_oapi::swagger_ui::Config;
264    /// let config = Config::new(["/api-docs/openapi.json"])
265    ///     .config_url("http://url.to.external.config");
266    /// ```
267    #[must_use]
268    pub fn config_url<S: Into<String>>(mut self, config_url: S) -> Self {
269        self.config_url = Some(config_url.into());
270
271        self
272    }
273
274    /// Add id of the DOM element where `Swagger UI` will put it's user interface.
275    ///
276    /// The default value is `#swagger-ui`.
277    ///
278    /// # Examples
279    ///
280    /// Set custom dom id where the Swagger UI will place it's content.
281    /// ```rust
282    /// # use salvo_oapi::swagger_ui::Config;
283    /// let config = Config::new(["/api-docs/openapi.json"]).dom_id("#my-id");
284    /// ```
285    #[must_use]
286    pub fn dom_id<S: Into<String>>(mut self, dom_id: S) -> Self {
287        self.dom_id = Some(dom_id.into());
288
289        self
290    }
291
292    /// Set `query_config_enabled` to allow overriding configuration parameters via url `query`
293    /// parameters.
294    ///
295    /// Default value is `false`.
296    ///
297    /// # Examples
298    ///
299    /// Enable query config.
300    /// ```rust
301    /// # use salvo_oapi::swagger_ui::Config;
302    /// let config = Config::new(["/api-docs/openapi.json"])
303    ///     .query_config_enabled(true);
304    /// ```
305    #[must_use] pub fn query_config_enabled(mut self, query_config_enabled: bool) -> Self {
306        self.query_config_enabled = Some(query_config_enabled);
307
308        self
309    }
310
311    /// Set `deep_linking` to allow deep linking tags and operations.
312    ///
313    /// Deep linking will automatically scroll to and expand operation when Swagger UI is
314    /// given corresponding url fragment. See more at
315    /// [deep linking docs](https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/deep-linking.md).
316    ///
317    /// Deep linking is enabled by default.
318    ///
319    /// # Examples
320    ///
321    /// Disable the deep linking.
322    /// ```rust
323    /// # use salvo_oapi::swagger_ui::Config;
324    /// let config = Config::new(["/api-docs/openapi.json"])
325    ///     .deep_linking(false);
326    /// ```
327    #[must_use] pub fn deep_linking(mut self, deep_linking: bool) -> Self {
328        self.deep_linking = Some(deep_linking);
329
330        self
331    }
332
333    /// Set `display_operation_id` to `true` to show operation id in the operations list.
334    ///
335    /// Default value is `false`.
336    ///
337    /// # Examples
338    ///
339    /// Allow operation id to be shown.
340    /// ```rust
341    /// # use salvo_oapi::swagger_ui::Config;
342    /// let config = Config::new(["/api-docs/openapi.json"])
343    ///     .display_operation_id(true);
344    /// ```
345    #[must_use] pub fn display_operation_id(mut self, display_operation_id: bool) -> Self {
346        self.display_operation_id = Some(display_operation_id);
347
348        self
349    }
350
351    /// Set 'layout' to 'BaseLayout' to only use the base swagger layout without a search header.
352    ///
353    /// Default value is 'StandaloneLayout'.
354    ///
355    /// # Examples
356    ///
357    /// Configure Swagger to use Base Layout instead of Standalone
358    /// ```rust
359    /// # use salvo_oapi::swagger_ui::Config;
360    /// let config = Config::new(["/api-docs/openapi.json"])
361    ///     .use_base_layout();
362    /// ```
363    #[must_use] pub fn use_base_layout(mut self) -> Self {
364        self.layout = SWAGGER_BASE_LAYOUT;
365
366        self
367    }
368
369    /// Add default models expansion depth.
370    ///
371    /// Setting this to `-1` will completely hide the models.
372    ///
373    /// # Examples
374    ///
375    /// Hide all the models.
376    /// ```rust
377    /// # use salvo_oapi::swagger_ui::Config;
378    /// let config = Config::new(["/api-docs/openapi.json"])
379    ///     .default_models_expand_depth(-1);
380    /// ```
381    #[must_use] pub fn default_models_expand_depth(mut self, default_models_expand_depth: isize) -> Self {
382        self.default_models_expand_depth = Some(default_models_expand_depth);
383
384        self
385    }
386
387    /// Add default model expansion depth for model on the example section.
388    ///
389    /// # Examples
390    ///
391    /// ```rust
392    /// # use salvo_oapi::swagger_ui::Config;
393    /// let config = Config::new(["/api-docs/openapi.json"])
394    ///     .default_model_expand_depth(1);
395    /// ```
396    #[must_use] pub fn default_model_expand_depth(mut self, default_model_expand_depth: isize) -> Self {
397        self.default_model_expand_depth = Some(default_model_expand_depth);
398
399        self
400    }
401
402    /// Add `default_model_rendering` to set how models is show when API is first rendered.
403    ///
404    /// The user can always switch the rendering for given model by clicking the `Model` and `Example Value` links.
405    ///
406    /// * `example` Makes example rendered first by default.
407    /// * `model` Makes model rendered first by default.
408    ///
409    /// # Examples
410    ///
411    /// ```rust
412    /// # use salvo_oapi::swagger_ui::Config;
413    /// let config = Config::new(["/api-docs/openapi.json"])
414    ///     .default_model_rendering(r#"["example"*, "model"]"#);
415    /// ```
416    #[must_use]
417    pub fn default_model_rendering<S: Into<String>>(mut self, default_model_rendering: S) -> Self {
418        self.default_model_rendering = Some(default_model_rendering.into());
419
420        self
421    }
422
423    /// Set to `true` to show request duration of _**'Try it out'**_ requests _**(in milliseconds)**_.
424    ///
425    /// Default value is `false`.
426    ///
427    /// # Examples
428    /// Enable request duration of the _**'Try it out'**_ requests.
429    /// ```rust
430    /// # use salvo_oapi::swagger_ui::Config;
431    /// let config = Config::new(["/api-docs/openapi.json"])
432    ///     .display_request_duration(true);
433    /// ```
434    #[must_use] pub fn display_request_duration(mut self, display_request_duration: bool) -> Self {
435        self.display_request_duration = Some(display_request_duration);
436
437        self
438    }
439
440    /// Add `doc_expansion` to control default expansion for operations and tags.
441    ///
442    /// * `list` Will expand only tags.
443    /// * `full` Will expand tags and operations.
444    /// * `none` Will expand nothing.
445    ///
446    /// # Examples
447    ///
448    /// ```rust
449    /// # use salvo_oapi::swagger_ui::Config;
450    /// let config = Config::new(["/api-docs/openapi.json"])
451    ///     .doc_expansion(r#"["list"*, "full", "none"]"#);
452    /// ```
453    #[must_use]
454    pub fn doc_expansion<S: Into<String>>(mut self, doc_expansion: S) -> Self {
455        self.doc_expansion = Some(doc_expansion.into());
456
457        self
458    }
459
460    /// Add `filter` to allow filtering of tagged operations.
461    ///
462    /// When enabled top bar will show and edit box that can be used to filter visible tagged operations.
463    /// Filter behaves case sensitive manner and matches anywhere inside the tag.
464    ///
465    /// Default value is `false`.
466    ///
467    /// # Examples
468    ///
469    /// Enable filtering.
470    /// ```rust
471    /// # use salvo_oapi::swagger_ui::Config;
472    /// let config = Config::new(["/api-docs/openapi.json"])
473    ///     .filter(true);
474    /// ```
475    #[must_use] pub fn filter(mut self, filter: bool) -> Self {
476        self.filter = Some(filter);
477
478        self
479    }
480
481    /// Add `max_displayed_tags` to restrict shown tagged operations.
482    ///
483    /// By default all operations are shown.
484    ///
485    /// # Examples
486    ///
487    /// Display only 4 operations.
488    /// ```rust
489    /// # use salvo_oapi::swagger_ui::Config;
490    /// let config = Config::new(["/api-docs/openapi.json"])
491    ///     .max_displayed_tags(4);
492    /// ```
493    #[must_use] pub fn max_displayed_tags(mut self, max_displayed_tags: usize) -> Self {
494        self.max_displayed_tags = Some(max_displayed_tags);
495
496        self
497    }
498
499    /// Set `show_extensions` to adjust whether vendor extension _**`(x-)`**_ fields and values
500    /// are shown for operations, parameters, responses and schemas.
501    ///
502    /// # Example
503    ///
504    /// Show vendor extensions.
505    /// ```rust
506    /// # use salvo_oapi::swagger_ui::Config;
507    /// let config = Config::new(["/api-docs/openapi.json"])
508    ///     .show_extensions(true);
509    /// ```
510    #[must_use] pub fn show_extensions(mut self, show_extensions: bool) -> Self {
511        self.show_extensions = Some(show_extensions);
512
513        self
514    }
515
516    /// Add `show_common_extensions` to define whether common extension
517    /// _**`(pattern, maxLength, minLength, maximum, minimum)`**_ fields and values are shown
518    /// for parameters.
519    ///
520    /// # Examples
521    ///
522    /// Show common extensions.
523    /// ```rust
524    /// # use salvo_oapi::swagger_ui::Config;
525    /// let config = Config::new(["/api-docs/openapi.json"])
526    ///     .show_common_extensions(true);
527    /// ```
528    #[must_use] pub fn show_common_extensions(mut self, show_common_extensions: bool) -> Self {
529        self.show_common_extensions = Some(show_common_extensions);
530
531        self
532    }
533
534    /// Add `try_it_out_enabled` to enable _**'Try it out'**_ section by default.
535    ///
536    /// Default value is `false`.
537    ///
538    /// # Examples
539    ///
540    /// Enable _**'Try it out'**_ section by default.
541    /// ```rust
542    /// # use salvo_oapi::swagger_ui::Config;
543    /// let config = Config::new(["/api-docs/openapi.json"])
544    ///     .try_it_out_enabled(true);
545    /// ```
546    #[must_use] pub fn try_it_out_enabled(mut self, try_it_out_enabled: bool) -> Self {
547        self.try_it_out_enabled = Some(try_it_out_enabled);
548
549        self
550    }
551
552    /// Set `request_snippets_enabled` to enable request snippets section.
553    ///
554    /// If disabled legacy curl snipped will be used.
555    ///
556    /// Default value is `false`.
557    ///
558    /// # Examples
559    ///
560    /// Enable request snippets section.
561    /// ```rust
562    /// # use salvo_oapi::swagger_ui::Config;
563    /// let config = Config::new(["/api-docs/openapi.json"])
564    ///     .request_snippets_enabled(true);
565    /// ```
566    #[must_use] pub fn request_snippets_enabled(mut self, request_snippets_enabled: bool) -> Self {
567        self.request_snippets_enabled = Some(request_snippets_enabled);
568
569        self
570    }
571
572    /// Add oauth redirect url.
573    ///
574    /// # Examples
575    ///
576    /// Add oauth redirect url.
577    /// ```rust
578    /// # use salvo_oapi::swagger_ui::Config;
579    /// let config = Config::new(["/api-docs/openapi.json"])
580    ///     .oauth2_redirect_url("http://my.oauth2.redirect.url");
581    /// ```
582    #[must_use]
583    pub fn oauth2_redirect_url<S: Into<String>>(mut self, oauth2_redirect_url: S) -> Self {
584        self.oauth2_redirect_url = Some(oauth2_redirect_url.into());
585
586        self
587    }
588
589    /// Add `show_mutated_request` to use request returned from `requestInterceptor`
590    /// to produce curl command in the UI. If set to `false` the request before `requestInterceptor`
591    /// was applied will be used.
592    ///
593    /// # Examples
594    ///
595    /// Use request after `requestInterceptor` to produce the curl command.
596    /// ```rust
597    /// # use salvo_oapi::swagger_ui::Config;
598    /// let config = Config::new(["/api-docs/openapi.json"])
599    ///     .show_mutated_request(true);
600    /// ```
601    #[must_use] pub fn show_mutated_request(mut self, show_mutated_request: bool) -> Self {
602        self.show_mutated_request = Some(show_mutated_request);
603
604        self
605    }
606
607    /// Add supported http methods for _**'Try it out'**_ operation.
608    ///
609    /// _**'Try it out'**_ will be enabled based on the given list of http methods when
610    /// the operation's http method is included within the list.
611    /// By giving an empty list will disable _**'Try it out'**_ from all operations but it will
612    /// **not** filter operations from the UI.
613    ///
614    /// By default all http operations are enabled.
615    ///
616    /// # Examples
617    ///
618    /// Set allowed http methods explicitly.
619    /// ```rust
620    /// # use salvo_oapi::swagger_ui::Config;
621    /// let config = Config::new(["/api-docs/openapi.json"])
622    ///     .supported_submit_methods(["get", "put", "post", "delete", "options", "head", "patch", "trace"]);
623    /// ```
624    ///
625    /// Allow _**'Try it out'**_ for only GET operations.
626    /// ```rust
627    /// # use salvo_oapi::swagger_ui::Config;
628    /// let config = Config::new(["/api-docs/openapi.json"])
629    ///     .supported_submit_methods(["get"]);
630    /// ```
631    #[must_use]
632    pub fn supported_submit_methods<I: IntoIterator<Item = S>, S: Into<String>>(
633        mut self,
634        supported_submit_methods: I,
635    ) -> Self {
636        self.supported_submit_methods = Some(
637            supported_submit_methods
638                .into_iter()
639                .map(|method| method.into())
640                .collect(),
641        );
642
643        self
644    }
645
646    /// Add validator url which is used to validate the Swagger spec.
647    ///
648    /// This can also be set to use locally deployed validator for example see
649    /// [Validator Badge](https://github.com/swagger-api/validator-badge) for more details.
650    ///
651    /// By default swagger.io's online validator _**`(https://validator.swagger.io/validator)`**_ will be used.
652    /// Setting this to `none` will disable the validator.
653    ///
654    /// # Examples
655    ///
656    /// Disable the validator.
657    /// ```rust
658    /// # use salvo_oapi::swagger_ui::Config;
659    /// let config = Config::new(["/api-docs/openapi.json"])
660    ///     .validator_url("none");
661    /// ```
662    #[must_use]
663    pub fn validator_url<S: Into<String>>(mut self, validator_url: S) -> Self {
664        self.validator_url = Some(validator_url.into());
665
666        self
667    }
668
669    /// Set `with_credentials` to enable passing credentials to CORS requests send by browser as defined
670    /// [fetch standards](https://fetch.spec.whatwg.org/#credentials).
671    ///
672    /// **Note**: that Swagger UI cannot currently set cookies cross-domain
673    /// (see [swagger-js#1163](https://github.com/swagger-api/swagger-js/issues/1163)) -
674    /// as a result, you will have to rely on browser-supplied cookies (which this setting enables sending)
675    /// that Swagger UI cannot control.
676    ///
677    /// # Examples
678    ///
679    /// Enable passing credentials to CORS requests.
680    /// ```rust
681    /// # use salvo_oapi::swagger_ui::Config;
682    /// let config = Config::new(["/api-docs/openapi.json"])
683    ///     .with_credentials(true);
684    /// ```
685    #[must_use] pub fn with_credentials(mut self, with_credentials: bool) -> Self {
686        self.with_credentials = Some(with_credentials);
687
688        self
689    }
690
691    /// Set to `true` to enable authorizations to be persisted throughout browser refresh and close.
692    ///
693    /// Default value is `false`.
694    ///
695    ///
696    /// # Examples
697    ///
698    /// Persists authorization throughout browser close and refresh.
699    /// ```rust
700    /// # use salvo_oapi::swagger_ui::Config;
701    /// let config = Config::new(["/api-docs/openapi.json"])
702    ///     .persist_authorization(true);
703    /// ```
704    #[must_use] pub fn persist_authorization(mut self, persist_authorization: bool) -> Self {
705        self.persist_authorization = Some(persist_authorization);
706
707        self
708    }
709}
710
711impl Default for Config<'_> {
712    fn default() -> Self {
713        Self {
714            config_url: Default::default(),
715            dom_id: Some("#swagger-ui".to_owned()),
716            url: Default::default(),
717            urls_primary_name: Default::default(),
718            urls: Default::default(),
719            query_config_enabled: Default::default(),
720            deep_linking: Some(true),
721            display_operation_id: Default::default(),
722            default_models_expand_depth: Default::default(),
723            default_model_expand_depth: Default::default(),
724            default_model_rendering: Default::default(),
725            display_request_duration: Default::default(),
726            doc_expansion: Default::default(),
727            filter: Default::default(),
728            max_displayed_tags: Default::default(),
729            show_extensions: Default::default(),
730            show_common_extensions: Default::default(),
731            try_it_out_enabled: Default::default(),
732            request_snippets_enabled: Default::default(),
733            oauth2_redirect_url: Default::default(),
734            show_mutated_request: Default::default(),
735            supported_submit_methods: Default::default(),
736            validator_url: Default::default(),
737            with_credentials: Default::default(),
738            persist_authorization: Default::default(),
739            oauth: Default::default(),
740            layout: SWAGGER_STANDALONE_LAYOUT,
741        }
742    }
743}
744
745impl<'a> From<&'a str> for Config<'a> {
746    fn from(s: &'a str) -> Self {
747        Self::new([s])
748    }
749}
750
751impl From<String> for Config<'_> {
752    fn from(s: String) -> Self {
753        Self::new([s])
754    }
755}
salvo_oapi/swagger_ui/config.rs

salvo_oapi/swagger_ui/
config.rs
