[OpenAPI] Add @ext_doc_id for endpoint externalDocs

Author: lcawl

compiler-rs/clients_schema/src/lib.rs

@@ -55,6 +55,11 @@ pub trait Documented {
     fn description(&self) -> Option<&str>;
 }
 
+pub trait ExternalDocument {
+    fn ext_doc_id(&self) -> Option<&str>;
+    fn ext_doc_url(&self) -> Option<&str>;
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct TypeName {
     // Order is important for Ord implementation
@@ -818,6 +823,12 @@ pub struct Endpoint {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub doc_tag: Option<String>,
 
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ext_doc_id: Option<String>,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ext_doc_url: Option<String>,
+
     /// If missing, there is not yet a request definition for this endpoint.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub request: Option<TypeName>,
@@ -854,6 +865,16 @@ impl Documented for Endpoint {
     }
 }
 
+impl ExternalDocument for Endpoint {
+    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(rename_all = "camelCase")]
 pub struct Privileges {

compiler-rs/clients_schema_to_openapi/src/paths.rs

@@ -203,8 +203,8 @@ pub fn add_endpoint(
             },
             summary: sum_desc.summary,
             description: sum_desc.description,
-            // external_docs: tac.convert_external_docs(endpoint),
-            external_docs: None, // Need values that differ from client purposes
+            external_docs: tac.convert_endpoint_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,
             request_body: request_body.clone(),

compiler-rs/clients_schema_to_openapi/src/schemas.rs

@@ -226,6 +226,23 @@ impl<'a> TypesAndComponents<'a> {
         })
     }
 
+    pub fn convert_endpoint_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
+                .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(),
+            }
+        })
+    }
+
     fn for_body(&mut self, body: &Body) -> anyhow::Result<Option<ReferenceOr<Schema>>> {
         let result = match body {
             Body::NoBody(_) => None,

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

@@ -68,6 +68,7 @@ export function compileEndpoints (): Record<string, model.Endpoint> {
       description: spec.documentation.description,
       docUrl: spec.documentation.url,
       docTag: spec.docTag,
+      extDocUrl: spec.externalDocs?.url,
       // Setting these values by default should be removed
       // when we no longer use rest-api-spec stubs as the
       // source of truth for stability/visibility.

compiler/src/model/build-model.ts

@@ -62,6 +62,10 @@ export interface JsonSpec {
     required?: boolean
   }
   docTag?: string
+  externalDocs?: {
+    url: string
+    description?: string
+  }
 }
 
 export default function buildJsonSpec (): Map<string, JsonSpec> {

compiler/src/model/json-spec.ts

@@ -406,6 +406,8 @@ export class Endpoint {
   description: string
   docUrl: string
   docId?: string
+  extDocId?: string
+  extDocUrl?: string
   deprecation?: Deprecation
   availability: Availabilities
   docTag?: string

compiler/src/model/metamodel.ts

@@ -625,7 +625,7 @@ export function hoistRequestAnnotations (
   request: model.Request, jsDocs: JSDoc[], mappings: Record<string, model.Endpoint>, response: model.TypeName | null
 ): void {
   const knownRequestAnnotations = [
-    'rest_spec_name', 'behavior', 'class_serializer', 'index_privileges', 'cluster_privileges', 'doc_id', 'availability', 'doc_tag'
+    'rest_spec_name', 'behavior', 'class_serializer', 'index_privileges', 'cluster_privileges', 'doc_id', 'availability', 'doc_tag', `ext_doc_id`
   ]
   // in most of the cases the jsDocs comes in a single block,
   // but it can happen that the user defines multiple single line jsDoc.
@@ -685,6 +685,12 @@ 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, '')
+    } 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()
+      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, '')
     } else if (tag === 'availability') {
       // The @availability jsTag is different than most because it allows
       // multiple values within the same docstring, hence needing to parse