salvo_oapi/redoc/
mod.rs

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

salvo_oapi/redoc/
mod.rs
