salvo_oapi/rapidoc/
mod.rs

1//! This crate implements necessary boiler plate code to serve RapiDoc via web server. It
2//! works as a bridge for serving the OpenAPI documentation created with [`salvo`][salvo] library in the
3//! RapiDoc.
4//!
5//! [salvo]: <https://docs.rs/salvo/>
6//!
7use std::borrow::Cow;
8
9use salvo_core::writing::Text;
10use salvo_core::{async_trait, Depot, FlowCtrl, Handler, Request, Response, Router};
11
12const INDEX_TMPL: &str = r#"
13<!doctype html>
14<html>
15  <head>
16    <title>{{title}}</title>
17    {{keywords}}
18    {{description}}
19    <meta charset="utf-8">
20    <script type="module" src="{{lib_url}}"></script>
21  </head>
22  <body>
23    <rapi-doc spec-url="{{spec_url}}"></rapi-doc>
24  </body>
25</html>
26"#;
27
28/// Implements [`Handler`] for serving RapiDoc.
29#[non_exhaustive]
30#[derive(Clone, Debug)]
31pub struct RapiDoc {
32    /// The title of the html page. The default title is "RapiDoc".
33    pub title: Cow<'static, str>,
34    /// The version of the html page.
35    pub keywords: Option<Cow<'static, str>>,
36    /// The description of the html page.
37    pub description: Option<Cow<'static, str>>,
38    /// The lib url path.
39    pub lib_url: Cow<'static, str>,
40    /// The spec url path.
41    pub spec_url: Cow<'static, str>,
42}
43impl RapiDoc {
44    /// Create a new [`RapiDoc`] for given path.
45    ///
46    /// Path argument will expose the RapiDoc to the user and should be something that
47    /// the underlying application framework / library supports.
48    ///
49    /// # Examples
50    ///
51    /// ```rust
52    /// # use salvo_oapi::rapidoc::RapiDoc;
53    /// let doc = RapiDoc::new("/openapi.json");
54    /// ```
55    pub fn new(spec_url: impl Into<Cow<'static, str>>) -> Self {
56        Self {
57            title: "RapiDoc".into(),
58            keywords: None,
59            description: None,
60            lib_url: "https://unpkg.com/rapidoc/dist/rapidoc-min.js".into(),
61            spec_url: spec_url.into(),
62        }
63    }
64
65    /// Set title of the html page. The default title is "RapiDoc".
66    pub fn title(mut self, title: impl Into<Cow<'static, str>>) -> Self {
67        self.title = title.into();
68        self
69    }
70
71    /// Set keywords of the html page.
72    pub fn keywords(mut self, keywords: impl Into<Cow<'static, str>>) -> Self {
73        self.keywords = Some(keywords.into());
74        self
75    }
76
77    /// Set description of the html page.
78    pub fn description(mut self, description: impl Into<Cow<'static, str>>) -> Self {
79        self.description = Some(description.into());
80        self
81    }
82
83    /// Set the lib url path.
84    pub fn lib_url(mut self, lib_url: impl Into<Cow<'static, str>>) -> Self {
85        self.lib_url = lib_url.into();
86        self
87    }
88
89    /// Consusmes the [`RapiDoc`] and returns [`Router`] with the [`RapiDoc`] as handler.
90    pub fn into_router(self, path: impl Into<String>) -> Router {
91        Router::with_path(path.into()).goal(self)
92    }
93}
94
95#[async_trait]
96impl Handler for RapiDoc {
97    async fn handle(&self, _req: &mut Request, _depot: &mut Depot, res: &mut Response, _ctrl: &mut FlowCtrl) {
98        let keywords = self
99            .keywords
100            .as_ref()
101            .map(|s| {
102                format!(
103                    "<meta name=\"keywords\" content=\"{}\">",
104                    s.split(',').map(|s| s.trim()).collect::<Vec<_>>().join(",")
105                )
106            })
107            .unwrap_or_default();
108        let description = self
109            .description
110            .as_ref()
111            .map(|s| format!("<meta name=\"description\" content=\"{}\">", s))
112            .unwrap_or_default();
113        let html = INDEX_TMPL
114            .replacen("{{spec_url}}", &self.spec_url, 1)
115            .replacen("{{lib_url}}", &self.lib_url, 1)
116            .replacen("{{description}}", &description, 1)
117            .replacen("{{keywords}}", &keywords, 1)
118            .replacen("{{title}}", &self.title, 1);
119        res.render(Text::Html(html));
120    }
121}
salvo_oapi/rapidoc/mod.rs

salvo_oapi/rapidoc/
mod.rs
