Merge multiple paths in a single operation

Author: swallez

compiler-rs/clients_schema_to_openapi/src/lib.rs

@@ -29,14 +29,23 @@ use crate::components::TypesAndComponents;
 
 pub struct Configuration {
     pub flavor: Option<Flavor>,
+
+    /// If a property value is an enumeration, the description of possible values will be copied in the
+    /// property's description (also works for arrays of enums).
     pub lift_enum_descriptions: bool,
+
+    /// Will output endpoints having multiple paths into a single operation. The operation's path will
+    /// be the longest one (with values for all optional parameters), and the other paths will be added
+    /// at the beginning of the operation's description.
+    pub merge_multipath_endpoints: bool,
 }
 
 impl Default for Configuration {
     fn default() -> Self {
         Self {
             flavor: None,
             lift_enum_descriptions: true,
+            merge_multipath_endpoints: true,
         }
     }
 }

compiler-rs/clients_schema_to_openapi/src/paths.rs

@@ -228,6 +228,67 @@ pub fn add_endpoint(
         // TODO: add error responses
     };
 
+    //---- Merge multipath endpoints if asked for
+    let mut new_endpoint: clients_schema::Endpoint;
+
+    let endpoint = if is_multipath && tac.config.merge_multipath_endpoints {
+        new_endpoint = endpoint.clone();
+        let endpoint = &mut new_endpoint;
+
+        // Sort paths from smallest to longest
+        endpoint.urls.sort_by_key(|x| x.path.len());
+
+        // Keep the longest and its last method so that the operation's path+method are the same as the last one
+        // (avoids the perception that it may have been chosen randomly).
+        let mut longest_path = endpoint.urls.last().unwrap().clone();
+        while longest_path.methods.len() > 1 {
+            longest_path.methods.remove(0);
+        }
+
+        // Replace endpoint urls with the longest path
+        let mut urls = vec![longest_path];
+        std::mem::swap(&mut endpoint.urls, &mut urls);
+
+        let split_desc = split_summary_desc(&endpoint.description);
+
+        // Make sure the description is stays at the top
+        let mut description = match split_desc.summary {
+            Some(summary) => format!("{summary}\n\n"),
+            None => String::new(),
+        };
+
+        // Convert removed paths to descriptions
+        write!(description, "**All methods and paths for this operation:**\n\n")?;
+
+        for url in urls {
+            for method in url.methods {
+                let lower_method = method.to_lowercase();
+                let path = &url.path;
+                write!(
+                    description,
+                    r#"<div><operation-summary>
+                      <span class="operation-verb {lower_method}">{method}</span>
+                      <span class="operation-path">{path}</span>
+                    </operation-summary></div>
+                    "#
+                )?;
+            }
+        }
+
+        if let Some(desc) = &split_desc.description {
+            write!(description, "\n\n{}", desc)?;
+        }
+
+        // Replace description
+        endpoint.description = description;
+
+        // Done
+        endpoint
+    } else {
+        // Not multipath or not asked to merge multipath
+        endpoint
+    };
+
     //---- Build a path for each url + method
     let mut operation_counter = 0;