[OpenAPI] Add description to externalDocs

Author: lcawl

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_doc_description(&self) -> Option<&str>;
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord, Hash)]
@@ -325,6 +326,9 @@ pub struct Property {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub ext_doc_id: Option<String>,
 
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ext_doc_description: Option<String>,
+
     #[serde(skip_serializing_if = "Option::is_none")]
     pub server_default: Option<ServerDefault>,
 
@@ -374,6 +378,10 @@ impl ExternalDocument for Property {
     fn ext_doc_id(&self) -> Option<&str> {
         self.ext_doc_id.as_deref()
     }
+
+    fn ext_doc_description(&self) -> Option<&str> {
+        self.ext_doc_description.as_deref()
+    }
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -505,6 +513,9 @@ pub struct BaseType {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub ext_doc_id: Option<String>,
 
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ext_doc_description: Option<String>,
+
     #[serde(skip_serializing_if = "Option::is_none")]
     pub deprecation: Option<Deprecation>,
 
@@ -542,6 +553,7 @@ impl BaseType {
             spec_location: None,
             ext_doc_id: None,
             ext_doc_url: None,
+            ext_doc_description: None,
         }
     }
 }
@@ -568,6 +580,10 @@ impl ExternalDocument for BaseType {
     fn ext_doc_id(&self) -> Option<&str> {
         self.ext_doc_id.as_deref()
     }
+
+    fn ext_doc_description(&self) -> Option<&str> {
+        self.ext_doc_description.as_deref()
+    }
 }
 
 trait WithBaseType {
@@ -590,11 +606,15 @@ impl<T: WithBaseType> Documented for T {
 
 impl<T: WithBaseType> ExternalDocument for T {
     fn ext_doc_url(&self) -> Option<&str> {
-        self.base().doc_url()
+        self.base().ext_doc_url()
     }
 
     fn ext_doc_id(&self) -> Option<&str> {
-        self.base().doc_id()
+        self.base().ext_doc_id()
+    }
+
+    fn ext_doc_description(&self) -> Option<&str> {
+        self.base().ext_doc_description()
     }
 }
 
@@ -865,6 +885,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_doc_description: Option<String>,
+
     #[serde(skip_serializing_if = "Option::is_none")]
     pub deprecation: Option<Deprecation>,
 
@@ -918,6 +941,10 @@ impl ExternalDocument for Endpoint {
     fn ext_doc_id(&self) -> Option<&str> {
         self.ext_doc_id.as_deref()
     }
+
+    fn ext_doc_description(&self) -> Option<&str> {
+        self.ext_doc_description.as_deref()
+    }
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]

compiler-rs/clients_schema_to_openapi/src/schemas.rs

@@ -219,7 +219,7 @@ impl<'a> TypesAndComponents<'a> {
                 .and_then(|i| i.version.as_deref())
                 .unwrap_or("current");
             ExternalDocumentation {
-                description: None,
+                description: obj.ext_doc_description().as_deref(),
                 url: url.trim().replace("{branch}", branch),
                 extensions: Default::default(),
             }

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

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

compiler-rs/openapi_to_clients_schema/src/types.rs

@@ -128,6 +128,7 @@ export class Property {
   docId?: string
   extDocId?: string
   extDocUrl?: string
+  extDocDesc?: string
   serverDefault?: boolean | string | number | string[] | number[]
   deprecation?: Deprecation
   availability?: Availabilities
@@ -162,6 +163,7 @@ export abstract class BaseType {
   docId?: string
   extDocId?: string
   extDocUrl?: string
+  extDocDesc?: string
   deprecation?: Deprecation
   /** If this endpoint has a quirk that needs special attention, give a short explanation about it */
   esQuirk?: string
@@ -412,6 +414,7 @@ export class Endpoint {
   docId?: string
   extDocId?: string
   extDocUrl?: string
+  extDocDesc?: string
   deprecation?: Deprecation
   availability: Availabilities
   docTag?: string

compiler/package-lock.json

@@ -691,6 +691,10 @@ export function hoistRequestAnnotations (
       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`)
       endpoint.extDocUrl = docUrl[1].replace(/\r/g, '')
+      const docDesc = docUrl[2].trim()
+      if (docDesc != null) {
+        endpoint.extDocDesc = docDesc
+      }
     } else if (tag === 'availability') {
       // The @availability jsTag is different than most because it allows
       // multiple values within the same docstring, hence needing to parse
@@ -754,6 +758,10 @@ export function hoistTypeAnnotations (type: model.TypeDefinition, jsDocs: JSDoc[
       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, '')
+      const docDesc = docUrl[2].trim()
+      if (docDesc != null) {
+        type.extDocDesc = docDesc
+      }
     } else if (tag === 'codegen_names') {
       type.codegenNames = parseCommaSeparated(value)
       assert(jsDocs,
@@ -826,6 +834,10 @@ function hoistPropertyAnnotations (property: model.Property, jsDocs: JSDoc[]): v
       const docUrl = docIds.find(entry => entry[0] === value)
       if (docUrl != null) {
         property.extDocUrl = docUrl[1].replace(/\r/g, '')
+        const docDesc = docUrl[2].trim()
+        if (docDesc != null) {
+          property.extDocDesc = docDesc
+        }
       }
     } 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}`)