Add ext_doc_id for all proparties

Author: lcawl

compiler-rs/clients_schema/src/lib.rs

@@ -319,6 +319,12 @@ pub struct Property {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub doc_id: Option<String>,
 
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ext_doc_url: Option<String>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ext_doc_id: Option<String>,
+
     #[serde(skip_serializing_if = "Option::is_none")]
     pub server_default: Option<ServerDefault>,
 
@@ -360,6 +366,16 @@ impl Documented for Property {
     }
 }
 
+impl ExternalDocument for Property {
+    fn ext_doc_url(&self) -> Option<&str> {
+        self.ext_doc_url.as_deref()
+    }
+
+    fn ext_doc_id(&self) -> Option<&str> {
+        self.ext_doc_id.as_deref()
+    }
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(untagged)]
 pub enum ServerDefault {
@@ -482,6 +498,13 @@ pub struct BaseType {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub doc_id: Option<String>,
 
+    /// Link to public documentation
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ext_doc_url: Option<String>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ext_doc_id: Option<String>,
+
     #[serde(skip_serializing_if = "Option::is_none")]
     pub deprecation: Option<Deprecation>,
 
@@ -517,6 +540,8 @@ impl BaseType {
             description: None,
             variant_name: None,
             spec_location: None,
+            ext_doc_id: None,
+            ext_doc_url: None,
         }
     }
 }
@@ -535,6 +560,16 @@ impl Documented for BaseType {
     }
 }
 
+impl ExternalDocument for BaseType {
+    fn ext_doc_url(&self) -> Option<&str> {
+        self.ext_doc_url.as_deref()
+    }
+
+    fn ext_doc_id(&self) -> Option<&str> {
+        self.ext_doc_id.as_deref()
+    }
+}
+
 trait WithBaseType {
     fn base(&self) -> &BaseType;
 }
@@ -553,6 +588,16 @@ impl<T: WithBaseType> Documented for T {
     }
 }
 
+impl<T: WithBaseType> ExternalDocument for T {
+    fn ext_doc_url(&self) -> Option<&str> {
+        self.base().doc_url()
+    }
+
+    fn ext_doc_id(&self) -> Option<&str> {
+        self.base().doc_id()
+    }
+}
+
 /// An interface type
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
@@ -815,19 +860,19 @@ pub struct Endpoint {
     pub doc_id: Option<String>,
 
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub deprecation: Option<Deprecation>,
+    pub ext_doc_id: Option<String>,
 
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub availability: Option<Availabilities>,
+    pub ext_doc_url: Option<String>,
 
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub doc_tag: Option<String>,
+    pub deprecation: Option<Deprecation>,
 
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub ext_doc_id: Option<String>,
+    pub availability: Option<Availabilities>,
 
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub ext_doc_url: Option<String>,
+    pub doc_tag: Option<String>,
 
     /// If missing, there is not yet a request definition for this endpoint.
     #[serde(skip_serializing_if = "Option::is_none")]

compiler-rs/clients_schema_to_openapi/src/paths.rs

@@ -203,7 +203,7 @@ pub fn add_endpoint(
             },
             summary: sum_desc.summary,
             description: sum_desc.description,
-            external_docs: tac.convert_endpoint_external_docs(endpoint),
+            external_docs: tac.convert_external_docs(endpoint),
             // external_docs: None, // Need values that differ from client purposes
             operation_id: None, // set in clone_operation below with operation_counter
             parameters,

compiler-rs/clients_schema_to_openapi/src/schemas.rs

@@ -209,24 +209,7 @@ impl<'a> TypesAndComponents<'a> {
         self.for_body(&response.body)
     }
 
-    pub fn convert_external_docs(&self, obj: &impl clients_schema::Documented) -> Option<ExternalDocumentation> {
-        // FIXME: does the model contain resolved doc_id?
-        obj.doc_url().map(|url| {
-            let branch: &str = self
-                .model
-                .info
-                .as_ref()
-                .and_then(|i| i.version.as_deref())
-                .unwrap_or("current");
-            ExternalDocumentation {
-                description: None,
-                url: url.trim().replace("{branch}", branch),
-                extensions: Default::default(),
-            }
-        })
-    }
-
-    pub fn convert_endpoint_external_docs(&self, obj: &impl clients_schema::ExternalDocument) -> Option<ExternalDocumentation> {
+    pub fn convert_external_docs(&self, obj: &impl clients_schema::ExternalDocument) -> Option<ExternalDocumentation> {
         // FIXME: does the model contain resolved doc_id?
         obj.ext_doc_url().map(|url| {
             let branch: &str = self

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

@@ -121,7 +121,7 @@ fn generate_type_for_schema(
         })
     }
     if let Some(ref docs) = data.external_docs {
-        base.doc_url = Some(docs.url.clone())
+        base.ext_doc_url = Some(docs.ext_docs_url.clone())
     }
 
     // TODO: data.readonly/writeonly -> OverloadOf?

compiler-rs/openapi_to_clients_schema/src/types.rs

@@ -126,6 +126,8 @@ export class Property {
   description?: string
   docUrl?: string
   docId?: string
+  extDocId?: string
+  extDocUrl?: string
   serverDefault?: boolean | string | number | string[] | number[]
   deprecation?: Deprecation
   availability?: Availabilities
@@ -158,6 +160,8 @@ export abstract class BaseType {
   /** Link to public documentation */
   docUrl?: string
   docId?: string
+  extDocId?: string
+  extDocUrl?: string
   deprecation?: Deprecation
   /** If this endpoint has a quirk that needs special attention, give a short explanation about it */
   esQuirk?: string

compiler/src/model/metamodel.ts

@@ -719,7 +719,7 @@ export function hoistTypeAnnotations (type: model.TypeDefinition, jsDocs: JSDoc[
   assert(jsDocs, jsDocs.length < 2, 'Use a single multiline jsDoc block instead of multiple single line blocks')
 
   const validTags = ['class_serializer', 'doc_url', 'doc_id', 'behavior', 'variants', 'variant', 'shortcut_property',
-    'codegen_names', 'non_exhaustive', 'es_quirk', 'behavior_meta']
+    'codegen_names', 'non_exhaustive', 'es_quirk', 'behavior_meta', 'ext_doc_id']
   const tags = parseJsDocTags(jsDocs)
   if (jsDocs.length === 1) {
     const description = jsDocs[0].getDescription()
@@ -748,7 +748,14 @@ export function hoistTypeAnnotations (type: model.TypeDefinition, jsDocs: JSDoc[
       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`)
       type.docUrl = docUrl[1].replace(/\r/g, '')
-    } else if (tag === 'codegen_names') {
+    } else if (tag === 'ext_doc_id') {
+      assert(jsDocs, value.trim() !== '', `Type ${type.name.namespace}.${type.name.name}'s @ext_doc_id cannot be empty`)
+      type.extDocId = value.trim()
+      const docUrl = docIds.find(entry => entry[0] === value.trim())
+      assert(jsDocs, docUrl != null, `The @ext_doc_id '${value.trim()}' is not present in _doc_ids/table.csv`)
+      type.extDocUrl = docUrl[1].replace(/\r/g, '')
+    }
+    else if (tag === 'codegen_names') {
       type.codegenNames = parseCommaSeparated(value)
       assert(jsDocs,
         type.kind === 'type_alias' && type.type.kind === 'union_of' && type.type.items.length === type.codegenNames.length,
@@ -770,7 +777,7 @@ function hoistPropertyAnnotations (property: model.Property, jsDocs: JSDoc[]): v
   assert(jsDocs, jsDocs.length < 2, 'Use a single multiline jsDoc block instead of multiple single line blocks')
 
   const validTags = ['prop_serializer', 'doc_url', 'aliases', 'codegen_name', 'server_default',
-    'variant', 'doc_id', 'es_quirk', 'availability']
+    'variant', 'doc_id', 'es_quirk', 'availability', 'ext_doc_id']
   const tags = parseJsDocTags(jsDocs)
   if (jsDocs.length === 1) {
     const description = jsDocs[0].getDescription()
@@ -814,6 +821,13 @@ function hoistPropertyAnnotations (property: model.Property, jsDocs: JSDoc[]): v
       if (docUrl != null) {
         property.docUrl = docUrl[1].replace(/\r/g, '')
       }
+    } else if (tag === 'ext_doc_id') {
+      assert(jsDocs, value.trim() !== '', `Property ${property.name}'s @ext_doc_id is cannot be empty`)
+      property.extDocId = value
+      const docUrl = docIds.find(entry => entry[0] === value)
+      if (docUrl != null) {
+        property.extDocUrl = docUrl[1].replace(/\r/g, '')
+      }
     } else if (tag === 'server_default') {
       assert(jsDocs, property.type.kind === 'instance_of' || property.type.kind === 'union_of' || property.type.kind === 'array_of', `Default values can only be configured for instance_of or union_of types, you are using ${property.type.kind}`)
       assert(jsDocs, !property.required, 'Default values can only be specified on optional properties')