Refactor Java API metadata

.chronus/changes/refactor-api-metadata-2026-08-04-13-50-00.md

@@ -0,0 +1,7 @@
+---
+changeKind: internal
+packages:
+  - "@typespec/http-client-java"
+---
+
+Centralize generated API metadata in a dedicated model.

packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/mapper/ClientMapper.java

@@ -24,6 +24,7 @@
 import com.microsoft.typespec.http.client.generator.core.extension.model.codemodel.SealedChoiceSchema;
 import com.microsoft.typespec.http.client.generator.core.extension.model.extensionmodel.XmsExtensions;
 import com.microsoft.typespec.http.client.generator.core.extension.plugin.JavaSettings;
+import com.microsoft.typespec.http.client.generator.core.model.clientmodel.ApiMetadata;
 import com.microsoft.typespec.http.client.generator.core.model.clientmodel.AsyncSyncClient;
 import com.microsoft.typespec.http.client.generator.core.model.clientmodel.ClassType;
 import com.microsoft.typespec.http.client.generator.core.model.clientmodel.Client;
@@ -342,7 +343,7 @@ public Client map(CodeModel codeModel) {
                         String clientBuilderName = clientName + builderSuffix;
                         ClientBuilder clientBuilder = new ClientBuilder(builderPackage, clientBuilderName,
                             serviceClient, (syncClient == null) ? List.of() : List.of(syncClient), List.of(asyncClient),
-                            serviceClient.getCrossLanguageDefinitionId());
+                            serviceClient.getApiMetadata());
 
                         addBuilderTraits(clientBuilder, serviceClient);
                         clientBuilders.add(clientBuilder);
@@ -356,7 +357,7 @@ public Client map(CodeModel codeModel) {
                 } else {
                     // service client builder
                     ClientBuilder clientBuilder = new ClientBuilder(builderPackage, builderName, serviceClient,
-                        syncClientsLocal, asyncClientsLocal, serviceClient.getCrossLanguageDefinitionId());
+                        syncClientsLocal, asyncClientsLocal, serviceClient.getApiMetadata());
                     addBuilderTraits(clientBuilder, serviceClient);
                     clientBuilders.add(clientBuilder);
 
@@ -370,7 +371,8 @@ public Client map(CodeModel codeModel) {
             asyncClients.addAll(asyncClientsLocal);
         }
         builder.clientBuilders(clientBuilders);
-        builder.crossLanguageDefinitionId(codeModel.getLanguage().getJava().getName());
+        builder.apiMetadata(
+            new ApiMetadata.Builder().crossLanguageDefinitionId(codeModel.getLanguage().getJava().getName()).build());
 
         // example/test
         if (settings.isDataPlaneClient() && (settings.isGenerateSamples() || settings.isGenerateTests())) {

packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/mapper/ClientMethodMapper.java

@@ -9,6 +9,7 @@
 import com.microsoft.typespec.http.client.generator.core.extension.plugin.JavaSettings;
 import com.microsoft.typespec.http.client.generator.core.extension.plugin.JavaSettings.SyncMethodsGeneration;
 import com.microsoft.typespec.http.client.generator.core.implementation.OperationInstrumentationInfo;
+import com.microsoft.typespec.http.client.generator.core.model.clientmodel.ApiMetadata;
 import com.microsoft.typespec.http.client.generator.core.model.clientmodel.ClassType;
 import com.microsoft.typespec.http.client.generator.core.model.clientmodel.ClientMethod;
 import com.microsoft.typespec.http.client.generator.core.model.clientmodel.ClientMethodParameter;
@@ -131,7 +132,11 @@ private List<ClientMethod> createClientMethods(Operation operation, boolean isPr
             .clientReference((operation.getOperationGroup() == null
                 || operation.getOperationGroup().getLanguage().getJava().getName().isEmpty()) ? "this" : "this.client")
             .operationInstrumentationInfo(new OperationInstrumentationInfo(operation))
-            .setCrossLanguageDefinitionId(SchemaUtil.getCrossLanguageDefinitionId(operation));
+            .apiMetadata(new ApiMetadata.Builder()
+                .crossLanguageDefinitionId(SchemaUtil.getCrossLanguageDefinitionId(operation))
+                .devMessage(
+                    operation.getLanguage().getJava() == null ? null : operation.getLanguage().getJava().getComment())
+                .build());
 
         setJavaDoc(builder, operation);
 
@@ -285,13 +290,6 @@ private static void setJavaDoc(ClientMethod.Builder builder, Operation operation
             builder.description(SchemaUtil.mergeSummaryWithDescription(summary, description));
         }
 
-        if (operation.getLanguage().getJava() != null
-            && !CoreUtils.isNullOrEmpty(operation.getLanguage().getJava().getComment())) {
-            // API comment.
-            builder.implementationDetails(
-                new ImplementationDetails.Builder().comment(operation.getLanguage().getJava().getComment()).build());
-        }
-
         if (operation.getExternalDocs() != null) {
             final ExternalDocumentation externalDocumentation
                 = new ExternalDocumentation.Builder().description(operation.getExternalDocs().getDescription())

packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/mapper/MapperUtils.java

@@ -10,6 +10,7 @@
 import com.microsoft.typespec.http.client.generator.core.extension.model.codemodel.Schema;
 import com.microsoft.typespec.http.client.generator.core.extension.model.codemodel.SchemaContext;
 import com.microsoft.typespec.http.client.generator.core.extension.plugin.JavaSettings;
+import com.microsoft.typespec.http.client.generator.core.model.clientmodel.ApiMetadata;
 import com.microsoft.typespec.http.client.generator.core.model.clientmodel.ClassType;
 import com.microsoft.typespec.http.client.generator.core.model.clientmodel.ClientEnumValue;
 import com.microsoft.typespec.http.client.generator.core.model.clientmodel.EnumType;
@@ -91,7 +92,9 @@ public static IType createEnumType(ChoiceSchema enumType, boolean expandable, bo
                 .implementationDetails(
                     new ImplementationDetails.Builder().usages(SchemaUtil.mapSchemaContext(enumType.getUsage()))
                         .build())
-                .crossLanguageDefinitionId(SchemaUtil.getCrossLanguageDefinitionId(enumType))
+                .apiMetadata(new ApiMetadata.Builder()
+                    .crossLanguageDefinitionId(SchemaUtil.getCrossLanguageDefinitionId(enumType))
+                    .build())
                 .fromMethodName(deserializationMethodName)
                 .toMethodName(serializationMethodName)
                 .build();

packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/mapper/MethodGroupMapper.java

@@ -7,6 +7,7 @@
 import com.microsoft.typespec.http.client.generator.core.extension.model.codemodel.Operation;
 import com.microsoft.typespec.http.client.generator.core.extension.model.codemodel.OperationGroup;
 import com.microsoft.typespec.http.client.generator.core.extension.plugin.JavaSettings;
+import com.microsoft.typespec.http.client.generator.core.model.clientmodel.ApiMetadata;
 import com.microsoft.typespec.http.client.generator.core.model.clientmodel.ClientMethod;
 import com.microsoft.typespec.http.client.generator.core.model.clientmodel.ClientModels;
 import com.microsoft.typespec.http.client.generator.core.model.clientmodel.IType;
@@ -166,7 +167,9 @@ private MethodGroupClient createMethodGroupClient(OperationGroup methodGroup,
                 .collect(Collectors.toList()));
         }
 
-        builder.crossLanguageDefinitionId(SchemaUtil.getCrossLanguageDefinitionId(methodGroup));
+        builder.apiMetadata(
+            new ApiMetadata.Builder().crossLanguageDefinitionId(SchemaUtil.getCrossLanguageDefinitionId(methodGroup))
+                .build());
 
         return builder.build();
     }

packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/mapper/ModelMapper.java

@@ -12,6 +12,7 @@
 import com.microsoft.typespec.http.client.generator.core.extension.model.codemodel.Schema;
 import com.microsoft.typespec.http.client.generator.core.extension.model.codemodel.XmlSerializationFormat;
 import com.microsoft.typespec.http.client.generator.core.extension.plugin.JavaSettings;
+import com.microsoft.typespec.http.client.generator.core.model.clientmodel.ApiMetadata;
 import com.microsoft.typespec.http.client.generator.core.model.clientmodel.ClassType;
 import com.microsoft.typespec.http.client.generator.core.model.clientmodel.ClientModel;
 import com.microsoft.typespec.http.client.generator.core.model.clientmodel.ClientModelProperty;
@@ -347,7 +348,9 @@ public ClientModel map(ObjectSchema compositeType) {
 
             builder.properties(properties);
             builder.propertyReferences(propertyReferences);
-            builder.crossLanguageDefinitionId(SchemaUtil.getCrossLanguageDefinitionId(compositeType));
+            builder.apiMetadata(new ApiMetadata.Builder()
+                .crossLanguageDefinitionId(SchemaUtil.getCrossLanguageDefinitionId(compositeType))
+                .build());
 
             result = builder.build();
 

packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/model/clientmodel/ApiMetadata.java

@@ -0,0 +1,83 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.typespec.http.client.generator.core.model.clientmodel;
+
+/**
+ * Metadata associated with a generated API.
+ */
+public final class ApiMetadata {
+    private final String crossLanguageDefinitionId;
+    private final String devMessage;
+
+    private ApiMetadata(String crossLanguageDefinitionId, String devMessage) {
+        this.crossLanguageDefinitionId = crossLanguageDefinitionId;
+        this.devMessage = devMessage;
+    }
+
+    /**
+     * Gets the cross-language definition ID.
+     *
+     * @return the cross-language definition ID.
+     */
+    public String getCrossLanguageDefinitionId() {
+        return crossLanguageDefinitionId;
+    }
+
+    /**
+     * Gets the message for SDK developers.
+     *
+     * @return the message for SDK developers.
+     */
+    public String getDevMessage() {
+        return devMessage;
+    }
+
+    /**
+     * Creates a builder initialized with this metadata.
+     *
+     * @return the initialized builder.
+     */
+    public Builder newBuilder() {
+        return new Builder().crossLanguageDefinitionId(crossLanguageDefinitionId).devMessage(devMessage);
+    }
+
+    /**
+     * Builder for {@link ApiMetadata}.
+     */
+    public static final class Builder {
+        private String crossLanguageDefinitionId;
+        private String devMessage;
+
+        /**
+         * Sets the cross-language definition ID.
+         *
+         * @param crossLanguageDefinitionId the cross-language definition ID.
+         * @return this builder.
+         */
+        public Builder crossLanguageDefinitionId(String crossLanguageDefinitionId) {
+            this.crossLanguageDefinitionId = crossLanguageDefinitionId;
+            return this;
+        }
+
+        /**
+         * Sets the message for SDK developers.
+         *
+         * @param devMessage the message for SDK developers.
+         * @return this builder.
+         */
+        public Builder devMessage(String devMessage) {
+            this.devMessage = devMessage;
+            return this;
+        }
+
+        /**
+         * Builds the API metadata.
+         *
+         * @return the API metadata.
+         */
+        public ApiMetadata build() {
+            return new ApiMetadata(crossLanguageDefinitionId, devMessage);
+        }
+    }
+}

packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/model/clientmodel/AsyncSyncClient.java

@@ -19,24 +19,24 @@ public class AsyncSyncClient {
     private final ServiceClient serviceClient;
 
     private final List<ConvenienceMethod> convenienceMethods;
-    private final String crossLanguageDefinitionId;
+    private final ApiMetadata apiMetadata;
 
     // There is also reference from Client to ClientBuilder via "@ServiceClient(builder = ClientBuilder.class)"
     // clientBuilder can be null, if builder is disabled via "disable-client-builder"
     private ClientBuilder clientBuilder;
 
     private AsyncSyncClient(String packageName, String className, MethodGroupClient methodGroupClient,
-        ServiceClient serviceClient, List<ConvenienceMethod> convenienceMethods, String crossLanguageDefinitionId) {
+        ServiceClient serviceClient, List<ConvenienceMethod> convenienceMethods, ApiMetadata apiMetadata) {
         this.packageName = packageName;
         this.className = className;
         this.methodGroupClient = methodGroupClient;
         this.serviceClient = serviceClient;
         this.convenienceMethods = convenienceMethods;
-        this.crossLanguageDefinitionId = crossLanguageDefinitionId;
+        this.apiMetadata = apiMetadata;
     }
 
-    public String getCrossLanguageDefinitionId() {
-        return crossLanguageDefinitionId;
+    public ApiMetadata getApiMetadata() {
+        return apiMetadata;
     }
 
     /**
@@ -125,7 +125,7 @@ public static class Builder {
         private ServiceClient serviceClient;
 
         private List<ConvenienceMethod> convenienceMethods = List.of();
-        private String crossLanguageDefinitionId;
+        private ApiMetadata apiMetadata = new ApiMetadata.Builder().build();
 
         /**
          * Sets the class name.
@@ -182,8 +182,8 @@ public Builder convenienceMethods(List<ConvenienceMethod> convenienceMethods) {
             return this;
         }
 
-        public Builder crossLanguageDefinitionId(String crossLanguageDefinitionId) {
-            this.crossLanguageDefinitionId = crossLanguageDefinitionId;
+        public Builder apiMetadata(ApiMetadata apiMetadata) {
+            this.apiMetadata = apiMetadata;
             return this;
         }
 
@@ -194,7 +194,7 @@ public Builder crossLanguageDefinitionId(String crossLanguageDefinitionId) {
          */
         public AsyncSyncClient build() {
             return new AsyncSyncClient(packageName, className, methodGroupClient, serviceClient, convenienceMethods,
-                crossLanguageDefinitionId);
+                apiMetadata);
         }
     }
 }

packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/model/clientmodel/Client.java

@@ -9,7 +9,7 @@
  * A container for the types associated for accessing a specific service.
  */
 public class Client {
-    private final String crossLanguageDefinitionId;
+    private final ApiMetadata apiMetadata;
 
     /**
      * The name of this service client.
@@ -91,7 +91,7 @@ private Client(String clientName, String clientDescription, List<EnumType> enums
         List<ServiceClient> serviceClients, ModuleInfo moduleInfo, List<AsyncSyncClient> syncClients,
         List<AsyncSyncClient> asyncClients, List<ClientBuilder> clientBuilders, List<ProtocolExample> protocolExamples,
         List<LiveTests> liveTests, List<UnionModel> unionModels, List<ClientMethodExample> clientMethodExamples,
-        String crossLanguageDefinitionId, GraalVmConfig graalVmConfig) {
+        ApiMetadata apiMetadata, GraalVmConfig graalVmConfig) {
         this.clientName = clientName;
         this.clientDescription = clientDescription;
         this.enums = enums;
@@ -111,12 +111,12 @@ private Client(String clientName, String clientDescription, List<EnumType> enums
         this.liveTests = liveTests;
         this.unionModels = unionModels;
         this.clientMethodExamples = clientMethodExamples;
-        this.crossLanguageDefinitionId = crossLanguageDefinitionId;
+        this.apiMetadata = apiMetadata;
         this.graalVmConfig = graalVmConfig;
     }
 
-    public String getCrossLanguageDefinitionId() {
-        return crossLanguageDefinitionId;
+    public ApiMetadata getApiMetadata() {
+        return apiMetadata;
     }
 
     public final String getClientName() {
@@ -227,10 +227,10 @@ public static class Builder {
         private List<UnionModel> unionModels = List.of();
         private List<ClientMethodExample> clientMethodExamples = List.of();
         private GraalVmConfig graalVmConfig;
-        private String crossLanguageDefinitionId;
+        private ApiMetadata apiMetadata = new ApiMetadata.Builder().build();
 
-        public Builder crossLanguageDefinitionId(String crossLanguageDefinitionId) {
-            this.crossLanguageDefinitionId = crossLanguageDefinitionId;
+        public Builder apiMetadata(ApiMetadata apiMetadata) {
+            this.apiMetadata = apiMetadata;
             return this;
         }
 
@@ -443,8 +443,8 @@ public Client build() {
             }
             return new Client(clientName, clientDescription, enums, exceptions, xmlSequenceWrappers, responseModels,
                 models, packageInfos, manager, serviceClient, serviceClients, moduleInfo, syncClients, asyncClients,
-                clientBuilders, protocolExamples, liveTests, unionModels, clientMethodExamples,
-                crossLanguageDefinitionId, graalVmConfig);
+                clientBuilders, protocolExamples, liveTests, unionModels, clientMethodExamples, apiMetadata,
+                graalVmConfig);
         }
     }
 }

packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/model/clientmodel/ClientBuilder.java

@@ -22,16 +22,16 @@ public class ClientBuilder {
     private final List<AsyncSyncClient> syncClients;
     private final List<AsyncSyncClient> asyncClients;
     private final List<ClientBuilderTrait> builderTraits = new ArrayList<>();
-    private String crossLanguageDefinitionId;
+    private final ApiMetadata apiMetadata;
 
     public ClientBuilder(String packageName, String className, ServiceClient serviceClient,
-        List<AsyncSyncClient> syncClients, List<AsyncSyncClient> asyncClients, String crossLanguageDefinitionId) {
+        List<AsyncSyncClient> syncClients, List<AsyncSyncClient> asyncClients, ApiMetadata apiMetadata) {
         this.packageName = Objects.requireNonNull(packageName);
         this.className = Objects.requireNonNull(className);
         this.serviceClient = Objects.requireNonNull(serviceClient);
         this.syncClients = Objects.requireNonNull(syncClients);
         this.asyncClients = Objects.requireNonNull(asyncClients);
-        this.crossLanguageDefinitionId = crossLanguageDefinitionId;
+        this.apiMetadata = apiMetadata;
     }
 
     public String getPackageName() {
@@ -80,7 +80,7 @@ public List<ClientBuilderTrait> getBuilderTraits() {
         return this.builderTraits;
     }
 
-    public String getCrossLanguageDefinitionId() {
-        return this.crossLanguageDefinitionId;
+    public ApiMetadata getApiMetadata() {
+        return apiMetadata;
     }
 }