[pdm-devel] [PATCH proxmox-backup v2 1/1] docgen: use proxmox-rs docgen crate

[Shannon Sterz <s.sterz@proxmox.com>]

this has the benefit of also handling the unstable flag correctly.
hence, the api viewer needs to add the css definitions to properly
render unstable endpoints.

Signed-off-by: Shannon Sterz <s.sterz@proxmox.com>
---
 Cargo.toml                 |   3 +
 docs/api-viewer/index.html |   2 +
 src/bin/docgen.rs          | 326 ++-----------------------------------
 3 files changed, 20 insertions(+), 311 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index 28fdbf54..fbd16ccb 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -62,6 +62,7 @@ proxmox-borrow = "1"
 proxmox-compression = "1.0.1"
 proxmox-config-digest = "1"
 proxmox-daemon = "1"
+proxmox-docgen = "1"
 proxmox-fuse = "1"
 proxmox-http = { version = "1.0.2", features = [ "client", "http-helpers", "websocket" ] } # see below
 proxmox-human-byte = "1"
@@ -216,6 +217,7 @@ proxmox-base64.workspace = true
 proxmox-compression.workspace = true
 proxmox-config-digest.workspace = true
 proxmox-daemon.workspace = true
+proxmox-docgen.workspace = true
 proxmox-http = { workspace = true, features = [ "body", "client-trait", "proxmox-async", "rate-limited-stream" ] } # pbs-client doesn't use these
 proxmox-human-byte.workspace = true
 proxmox-io.workspace = true
@@ -275,6 +277,7 @@ proxmox-rrd-api-types.workspace = true
 #proxmox-compression = { path = "../proxmox/proxmox-compression" }
 #proxmox-config-digest = { path = "../proxmox/proxmox-config-digest" }
 #proxmox-daemon = { path = "../proxmox/proxmox-daemon" }
+#proxmox-docgen = { path = "../proxmox/proxmox-docgen" }
 #proxmox-http = { path = "../proxmox/proxmox-http" }
 #proxmox-http-error = { path = "../proxmox/proxmox-http-error" }
 #proxmox-human-byte = { path = "../proxmox/proxmox-human-byte" }
diff --git a/docs/api-viewer/index.html b/docs/api-viewer/index.html
index 72dae96a..28f5b3b7 100644
--- a/docs/api-viewer/index.html
+++ b/docs/api-viewer/index.html
@@ -6,6 +6,8 @@
     <title>Proxmox Backup Server API Documentation</title>
 
     <link rel="stylesheet" type="text/css" href="extjs/theme-crisp/resources/theme-crisp-all.css">
+    <link rel="stylesheet" type="text/css" href="/fontawesome/css/font-awesome.css" />
+    <link rel="stylesheet" type="text/css" href="/widgettoolkit/css/ext6-pmx.css" />
     <link rel="stylesheet" type="text/css" media="(prefers-color-scheme: dark)" href="/widgettoolkit/themes/theme-proxmox-dark.css" />
     <script type="text/javascript" src="extjs/ext-all.js"></script>
     <script type="text/javascript" src="apidoc.js"></script>
diff --git a/src/bin/docgen.rs b/src/bin/docgen.rs
index 674be945..04d2de29 100644
--- a/src/bin/docgen.rs
+++ b/src/bin/docgen.rs
@@ -1,9 +1,7 @@
 use anyhow::{bail, Error};
-use serde_json::{json, Value};
 
-use proxmox_router::{ApiAccess, ApiHandler, ApiMethod, Permission, Router, SubRoute};
-use proxmox_schema::format::{dump_enum_properties, get_property_string_type_text};
-use proxmox_schema::{ApiStringFormat, ApiType, ObjectSchemaType, Schema};
+use proxmox_schema::format::dump_enum_properties;
+use proxmox_schema::ApiType;
 use proxmox_section_config::dump_section_config;
 
 use pbs_api_types::PRIVILEGES;
@@ -55,22 +53,30 @@ fn main() -> Result<(), Error> {
 fn generate_api_tree() -> String {
     let mut tree = Vec::new();
 
-    let mut data = dump_api_schema(&api2::ROUTER, ".");
+    let mut data = proxmox_docgen::generate_api_tree(&api2::ROUTER, ".", PRIVILEGES);
     data["path"] = "/".into();
     // hack: add invisible space to sort as first entry
     data["text"] = "&#x200b;Management API (HTTP)".into();
-    data["expanded"] = true.into();
-
     tree.push(data);
 
-    let mut data = dump_api_schema(&api2::backup::BACKUP_API_ROUTER, "/backup/_upgrade_");
+    let mut data = proxmox_docgen::generate_api_tree(
+        &api2::backup::BACKUP_API_ROUTER,
+        "/backup/_upgrade_",
+        PRIVILEGES,
+    );
     data["path"] = "/backup/_upgrade_".into();
     data["text"] = "Backup API (HTTP/2)".into();
+    data["expanded"] = false.into();
     tree.push(data);
 
-    let mut data = dump_api_schema(&api2::reader::READER_API_ROUTER, "/reader/_upgrade_");
+    let mut data = proxmox_docgen::generate_api_tree(
+        &api2::reader::READER_API_ROUTER,
+        "/reader/_upgrade_",
+        PRIVILEGES,
+    );
     data["path"] = "/reader/_upgrade_".into();
     data["text"] = "Restore API (HTTP/2)".into();
+    data["expanded"] = false.into();
     tree.push(data);
 
     format!(
@@ -78,305 +84,3 @@ fn generate_api_tree() -> String {
         serde_json::to_string_pretty(&tree).unwrap()
     )
 }
-
-pub fn dump_schema(schema: &Schema) -> Value {
-    let mut data;
-
-    match schema {
-        Schema::Null => {
-            data = json!({
-                "type": "null",
-            });
-        }
-        Schema::Boolean(boolean_schema) => {
-            data = json!({
-                "type": "boolean",
-                "description": boolean_schema.description,
-            });
-            if let Some(default) = boolean_schema.default {
-                data["default"] = default.into();
-            }
-        }
-        Schema::String(string_schema) => {
-            data = json!({
-                "type": "string",
-                "description": string_schema.description,
-            });
-            if let Some(default) = string_schema.default {
-                data["default"] = default.into();
-            }
-            if let Some(min_length) = string_schema.min_length {
-                data["minLength"] = min_length.into();
-            }
-            if let Some(max_length) = string_schema.max_length {
-                data["maxLength"] = max_length.into();
-            }
-            if let Some(type_text) = string_schema.type_text {
-                data["typetext"] = type_text.into();
-            }
-            match string_schema.format {
-                None | Some(ApiStringFormat::VerifyFn(_)) => { /* do nothing */ }
-                Some(ApiStringFormat::Pattern(const_regex)) => {
-                    data["pattern"] = format!("/{}/", const_regex.regex_string).into();
-                }
-                Some(ApiStringFormat::Enum(variants)) => {
-                    let variants: Vec<String> =
-                        variants.iter().map(|e| e.value.to_string()).collect();
-                    data["enum"] = serde_json::to_value(variants).unwrap();
-                }
-                Some(ApiStringFormat::PropertyString(subschema)) => {
-                    match subschema {
-                        Schema::Object(_) | Schema::Array(_) => {
-                            data["format"] = dump_schema(subschema);
-                            data["typetext"] = get_property_string_type_text(subschema).into();
-                        }
-                        _ => { /* do nothing  - should not happen */ }
-                    };
-                }
-            }
-            // fixme: dump format
-        }
-        Schema::Integer(integer_schema) => {
-            data = json!({
-                "type": "integer",
-                "description": integer_schema.description,
-            });
-            if let Some(default) = integer_schema.default {
-                data["default"] = default.into();
-            }
-            if let Some(minimum) = integer_schema.minimum {
-                data["minimum"] = minimum.into();
-            }
-            if let Some(maximum) = integer_schema.maximum {
-                data["maximum"] = maximum.into();
-            }
-        }
-        Schema::Number(number_schema) => {
-            data = json!({
-                "type": "number",
-                "description": number_schema.description,
-            });
-            if let Some(default) = number_schema.default {
-                data["default"] = default.into();
-            }
-            if let Some(minimum) = number_schema.minimum {
-                data["minimum"] = minimum.into();
-            }
-            if let Some(maximum) = number_schema.maximum {
-                data["maximum"] = maximum.into();
-            }
-        }
-        Schema::Object(object_schema) => {
-            data = dump_property_schema(object_schema);
-            data["type"] = "object".into();
-            if let Some(default_key) = object_schema.default_key {
-                data["default_key"] = default_key.into();
-            }
-        }
-        Schema::Array(array_schema) => {
-            data = json!({
-                "type": "array",
-                "description": array_schema.description,
-                "items": dump_schema(array_schema.items),
-            });
-            if let Some(min_length) = array_schema.min_length {
-                data["minLength"] = min_length.into();
-            }
-            if let Some(max_length) = array_schema.min_length {
-                data["maxLength"] = max_length.into();
-            }
-        }
-        Schema::AllOf(alloff_schema) => {
-            data = dump_property_schema(alloff_schema);
-            data["type"] = "object".into();
-        }
-        Schema::OneOf(schema) => {
-            let mut type_schema = dump_schema(schema.type_schema());
-            if schema.type_property_entry.1 {
-                type_schema["optional"] = true.into();
-            }
-            data = json!({
-                "type": "object",
-                "description": schema.description,
-                "typeProperty": schema.type_property(),
-                "typeSchema": type_schema,
-            });
-            let mut variants = Vec::with_capacity(schema.list.len());
-            for (title, variant) in schema.list {
-                let mut entry = dump_schema(variant);
-                entry["title"] = (*title).into();
-                variants.push(entry);
-            }
-            data["oneOf"] = variants.into();
-        }
-    };
-
-    data
-}
-
-pub fn dump_property_schema(param: &dyn ObjectSchemaType) -> Value {
-    let mut properties = json!({});
-
-    for (prop, optional, schema) in param.properties() {
-        let mut property = dump_schema(schema);
-        if *optional {
-            property["optional"] = 1.into();
-        }
-        properties[prop] = property;
-    }
-
-    let data = json!({
-        "description": param.description(),
-        "additionalProperties": param.additional_properties(),
-        "properties": properties,
-    });
-
-    data
-}
-
-fn dump_api_permission(permission: &Permission) -> Value {
-    match permission {
-        Permission::Superuser => json!({ "user": "root@pam" }),
-        Permission::User(user) => json!({ "user": user }),
-        Permission::Anybody => json!({ "user": "all" }),
-        Permission::World => json!({ "user": "world" }),
-        Permission::UserParam(param) => json!({ "userParam": param }),
-        Permission::Group(group) => json!({ "group": group }),
-        Permission::WithParam(param, sub_permission) => {
-            json!({
-                "withParam": {
-                    "name": param,
-                    "permissions": dump_api_permission(sub_permission),
-                },
-            })
-        }
-        Permission::Privilege(name, value, partial) => {
-            let mut privs = Vec::new();
-            for (name, v) in PRIVILEGES {
-                if (value & v) != 0 {
-                    privs.push(name.to_string());
-                }
-            }
-
-            json!({
-                "check": {
-                    "path": name,
-                    "privs": privs,
-                    "partial": partial,
-                }
-            })
-        }
-        Permission::And(list) => {
-            let list: Vec<Value> = list.iter().map(|p| dump_api_permission(p)).collect();
-            json!({ "and": list })
-        }
-        Permission::Or(list) => {
-            let list: Vec<Value> = list.iter().map(|p| dump_api_permission(p)).collect();
-            json!({ "or": list })
-        }
-    }
-}
-
-fn dump_api_method_schema(method: &str, api_method: &ApiMethod) -> Value {
-    let mut data = json!({
-        "description": api_method.parameters.description(),
-    });
-
-    data["parameters"] = dump_property_schema(&api_method.parameters);
-
-    let mut returns = dump_schema(api_method.returns.schema);
-    if api_method.returns.optional {
-        returns["optional"] = 1.into();
-    }
-    data["returns"] = returns;
-
-    match api_method.access {
-        ApiAccess {
-            description: None,
-            permission: Permission::Superuser,
-        } => {
-            // no need to output default
-        }
-        ApiAccess {
-            description,
-            permission,
-        } => {
-            let mut permissions = dump_api_permission(permission);
-            if let Some(description) = description {
-                permissions["description"] = description.into();
-            }
-            data["permissions"] = permissions;
-        }
-    }
-
-    let mut method = method;
-
-    if let ApiHandler::AsyncHttp(_) = api_method.handler {
-        method = if method == "POST" { "UPLOAD" } else { method };
-        method = if method == "GET" { "DOWNLOAD" } else { method };
-    }
-
-    data["method"] = method.into();
-
-    data
-}
-
-pub fn dump_api_schema(router: &Router, path: &str) -> Value {
-    let mut data = json!({});
-
-    let mut info = json!({});
-    if let Some(api_method) = router.get {
-        info["GET"] = dump_api_method_schema("GET", api_method);
-    }
-    if let Some(api_method) = router.post {
-        info["POST"] = dump_api_method_schema("POST", api_method);
-    }
-    if let Some(api_method) = router.put {
-        info["PUT"] = dump_api_method_schema("PUT", api_method);
-    }
-    if let Some(api_method) = router.delete {
-        info["DELETE"] = dump_api_method_schema("DELETE", api_method);
-    }
-
-    data["info"] = info;
-
-    match &router.subroute {
-        None => {
-            data["leaf"] = 1.into();
-        }
-        Some(SubRoute::MatchAll { router, param_name }) => {
-            let sub_path = if path == "." {
-                format!("/{{{param_name}}}")
-            } else {
-                format!("{path}/{{{param_name}}}")
-            };
-            let mut child = dump_api_schema(router, &sub_path);
-            child["path"] = sub_path.into();
-            child["text"] = format!("{{{param_name}}}").into();
-
-            let children = vec![child];
-            data["children"] = children.into();
-            data["leaf"] = 0.into();
-        }
-        Some(SubRoute::Map(dirmap)) => {
-            let mut children = Vec::new();
-
-            for (key, sub_router) in dirmap.iter() {
-                let sub_path = if path == "." {
-                    format!("/{key}")
-                } else {
-                    format!("{path}/{key}")
-                };
-                let mut child = dump_api_schema(sub_router, &sub_path);
-                child["path"] = sub_path.into();
-                child["text"] = key.to_string().into();
-                children.push(child);
-            }
-
-            data["children"] = children.into();
-            data["leaf"] = 0.into();
-        }
-    }
-
-    data
-}
-- 
2.47.3



_______________________________________________
pdm-devel mailing list
pdm-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pdm-devel