Add previous version documentation URLs to schema and OpenAPI (#4638) (#4646)

Author: miguelgrinberg

compiler-rs/clients_schema/src/lib.rs

@@ -58,6 +58,7 @@ pub trait Documented {
 pub trait ExternalDocument {
     fn ext_doc_id(&self) -> Option<&str>;
     fn ext_doc_url(&self) -> Option<&str>;
+    fn ext_previous_version_doc_url(&self) -> Option<&str>;
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord, Hash)]
@@ -322,6 +323,9 @@ pub struct Property {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub ext_doc_url: Option<String>,
 
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ext_previous_version_doc_url: Option<String>,
+
     #[serde(skip_serializing_if = "Option::is_none")]
     pub ext_doc_id: Option<String>,
 
@@ -371,6 +375,10 @@ impl ExternalDocument for Property {
         self.ext_doc_url.as_deref()
     }
 
+    fn ext_previous_version_doc_url(&self) -> Option<&str> {
+        self.ext_previous_version_doc_url.as_deref()
+    }
+
     fn ext_doc_id(&self) -> Option<&str> {
         self.ext_doc_id.as_deref()
     }
@@ -528,6 +536,9 @@ pub struct BaseType {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub ext_doc_url: Option<String>,
 
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ext_previous_version_doc_url: Option<String>,
+
     #[serde(skip_serializing_if = "Option::is_none")]
     pub ext_doc_id: Option<String>,
 
@@ -568,6 +579,7 @@ impl BaseType {
             spec_location: None,
             ext_doc_id: None,
             ext_doc_url: None,
+            ext_previous_version_doc_url: None,
         }
     }
 }
@@ -591,6 +603,10 @@ impl ExternalDocument for BaseType {
         self.ext_doc_url.as_deref()
     }
 
+    fn ext_previous_version_doc_url(&self) -> Option<&str> {
+        self.ext_previous_version_doc_url.as_deref()
+    }
+
     fn ext_doc_id(&self) -> Option<&str> {
         self.ext_doc_id.as_deref()
     }
@@ -619,6 +635,10 @@ impl<T: WithBaseType> ExternalDocument for T {
         self.base().doc_url()
     }
 
+    fn ext_previous_version_doc_url(&self) -> Option<&str> {
+        self.base().ext_previous_version_doc_url()
+    }
+
     fn ext_doc_id(&self) -> Option<&str> {
         self.base().doc_id()
     }
@@ -895,6 +915,9 @@ pub struct Endpoint {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub ext_doc_url: Option<String>,
 
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ext_previous_version_doc_url: Option<String>,
+
     #[serde(skip_serializing_if = "Option::is_none")]
     pub deprecation: Option<Deprecation>,
 
@@ -945,6 +968,10 @@ impl ExternalDocument for Endpoint {
         self.ext_doc_url.as_deref()
     }
 
+    fn ext_previous_version_doc_url(&self) -> Option<&str> {
+        self.ext_previous_version_doc_url.as_deref()
+    }
+
     fn ext_doc_id(&self) -> Option<&str> {
         self.ext_doc_id.as_deref()
     }

compiler-rs/clients_schema_to_openapi/src/schemas.rs

@@ -215,10 +215,14 @@ impl<'a> TypesAndComponents<'a> {
                 .as_ref()
                 .and_then(|i| i.version.as_deref())
                 .unwrap_or("current");
+            let mut extensions: IndexMap<String,serde_json::Value> = Default::default();
+            if let Some(previous_version_doc_url) = obj.ext_previous_version_doc_url() {
+                extensions.insert("x-previousVersionUrl".to_string(), serde_json::json!(previous_version_doc_url));
+            }
             ExternalDocumentation {
                 description: None,
                 url: url.trim().replace("{branch}", branch),
-                extensions: Default::default(),
+                extensions,
             }
         })
     }

compiler-rs/compiler-wasm-lib/pkg/compiler_wasm_lib.js

@@ -404,6 +404,7 @@ fn generate_interface_def(
             doc_url: None,
             ext_doc_id: None,
             ext_doc_url: None,
+            ext_previous_version_doc_url: None,
             codegen_name: None, // FIXME: extension in workplace search
             description: None,
             aliases: Vec::default(),

compiler-rs/compiler-wasm-lib/pkg/compiler_wasm_lib_bg.wasm

@@ -443,6 +443,7 @@ export class Endpoint {
   docId?: string
   extDocId?: string
   extDocUrl?: string
+  extPreviousVersionDocUrl?: string
   deprecation?: Deprecation
   availability: Availabilities
   docTag?: string

compiler-rs/openapi_to_clients_schema/src/types.rs

@@ -694,6 +694,9 @@ export function hoistRequestAnnotations (
       const docUrl = docIds.find(entry => entry[0] === value.trim())
       assert(jsDocs, docUrl != null, `The @doc_id '${value.trim()}' is not present in _doc_ids/table.csv`)
       endpoint.docUrl = docUrl[1].replace(/\r/g, '')
+      if (docUrl[2].replace(/\r/g, '') !== '') {
+        endpoint.extPreviousVersionDocUrl = docUrl[2].replace(/\r/g, '')
+      }
     } else if (tag === 'ext_doc_id') {
       assert(jsDocs, value.trim() !== '', `Request ${request.name.name}'s @ext_doc_id cannot be empty`)
       endpoint.extDocId = value.trim()