Add doc_tag

Author: lcawl

compiler-rs/clients_schema/src/lib.rs

@@ -815,6 +815,9 @@ pub struct Endpoint {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub availability: Option<Availabilities>,
 
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub doc_tag: 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>,

compiler-rs/clients_schema_to_openapi/src/paths.rs

@@ -196,7 +196,7 @@ pub fn add_endpoint(
 
         // Create the operation, it will be repeated if we have several methods
         let operation = openapiv3::Operation {
-            tags: vec![namespace.to_string()],
+            tags: if endpoint.doc_tag.is_some() {vec![endpoint.doc_tag.clone().expect("TODO: panic message")]} else {vec![namespace.to_string()]},
             summary: sum_desc.summary,
             description: sum_desc.description,
             // external_docs: tac.convert_external_docs(endpoint),

compiler-rs/clients_schema_to_openapi/src/schemas.rs

@@ -38,7 +38,7 @@ const SCHEMA_PLACEHOLDER: ReferenceOr<Schema> = ReferenceOr::Reference {
 /// Convert `schema.json` type and value definitions to OpenAPI schemas:
 ///
 /// The `convert_*` functions return a concrete schema and not a reference and do not store them in
-/// the OpenAPI `components.schema`. This is the role of `for_type_name` hat creates and stores the
+/// the OpenAPI `components.schema`. This is the role of `for_type_name` that creates and stores the
 /// schema and returns a reference.
 impl<'a> TypesAndComponents<'a> {
     /// Convert a value. Returns a schema reference and not a concrete schema, as values can

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

@@ -67,6 +67,7 @@ export function compileEndpoints (): Record<string, model.Endpoint> {
       name: api,
       description: spec.documentation.description,
       docUrl: spec.documentation.url,
+      docTag: spec.docTag,
       // 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

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

compiler/src/model/json-spec.ts

@@ -408,7 +408,7 @@ export class Endpoint {
   docId?: string
   deprecation?: Deprecation
   availability: Availabilities
-
+  docTag?: string
   /**
    * If the request value is `null` it means that there is not yet a
    * request type definition for this endpoint.

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'
+    'rest_spec_name', 'behavior', 'class_serializer', 'index_privileges', 'cluster_privileges', 'doc_id', 'availability', 'doc_tag'
   ]
   // in most of the cases the jsDocs comes in a single block,
   // but it can happen that the user defines multiple single line jsDoc.
@@ -696,6 +696,9 @@ export function hoistRequestAnnotations (
       for (const [availabilityName, availabilityValue] of Object.entries(availabilities)) {
         endpoint.availability[availabilityName] = availabilityValue
       }
+    } else if (tag === 'doc_tag') {
+      assert(jsDocs, value.trim() !== '', `Request ${request.name.name}'s @doc_tag cannot be empty`)
+      endpoint.docTag = value.trim()
     } else {
       assert(jsDocs, false, `Unhandled tag: '${tag}' with value: '${value}' on request ${request.name.name}`)
     }