[tcgc] add @isApiVersion decorator (#1978)

fixes #1706 cc @jhendrixMSFT also, fix some typo for decorator docs. --------- Co-authored-by: iscai-msft <[email protected]> Co-authored-by: tadelesh <[email protected]>
Azure · Dec 19, 2024 · 1c64037 · 1c64037
1 parent 4e74671
commit 1c64037
Show file tree

Hide file tree

Showing 11 changed files with 496 additions and 144 deletions.
diff --git a/.chronus/changes/tcgc-isApiVersion-2024-11-11-19-2-29.md b/.chronus/changes/tcgc-isApiVersion-2024-11-11-19-2-29.md
@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@azure-tools/typespec-client-generator-core"
+---
+
+Add `@isApiVersion` decorator to override whether a parameter is an api version or not
diff --git a/packages/typespec-client-generator-core/README.md b/packages/typespec-client-generator-core/README.md
diff --git a/packages/typespec-client-generator-core/generated-defs/Azure.ClientGenerator.Core.ts b/packages/typespec-client-generator-core/generated-defs/Azure.ClientGenerator.Core.ts
@@ -15,7 +15,7 @@ import type {
  * Changes the name of a method, parameter, property, or model generated in the client SDK
  *
  * @param rename The rename you want applied to the object
- * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters.
  * You can use "!" to specify negation such as "!(java, python)" or "!java, !python".
  * @example
  * ```typespec
@@ -42,7 +42,7 @@ export type ClientNameDecorator = (
  * Whether you want to generate an operation as a convenient operation.
  *
  * @param value Whether to generate the operation as convenience method or not.
- * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters.
  * You can use "!" to specify negation such as "!(java, python)" or "!java, !python".
  * @example
  * ```typespec
@@ -61,7 +61,7 @@ export type ConvenientAPIDecorator = (
  * Whether you want to generate an operation as a protocol operation.
  *
  * @param value Whether to generate the operation as protocol or not.
- * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters.
  * You can use "!" to specify negation such as "!(java, python)" or "!java, !python".
  * @example
  * ```typespec
@@ -80,7 +80,7 @@ export type ProtocolAPIDecorator = (
  * Create a ClientGenerator.Core client out of a namespace or interface
  *
  * @param value Optional configuration for the service.
- * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters.
  * You can use "!" to specify negation such as "!(java, python)" or "!java, !python".
  * @example Basic client setting
  * ```typespec
@@ -113,7 +113,7 @@ export type ClientDecorator = (
 /**
  * Create a ClientGenerator.Core operation group out of a namespace or interface
  *
- * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters.
  * You can use "!" to specify negation such as "!(java, python)" or "!java, !python".
  * @example
  * ```typespec
@@ -145,7 +145,7 @@ export type OperationGroupDecorator = (
  * otherwise a warning will be added to diagnostics list.
  *
  * @param value The usage info you want to set for this model.
- * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters.
  * You can use "!" to specify negation such as "!(java, python)" or "!java, !python".
  * @example Expand usage for model
  * ```typespec
@@ -217,7 +217,7 @@ export type UsageDecorator = (
  * otherwise a warning will be added to diagnostics list.
  *
  * @param value The access info you want to set for this model or operation.
- * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters.
  * You can use "!" to specify negation such as "!(java, python)" or "!java, !python".
  * @example Set access
  * ```typespec
@@ -353,7 +353,7 @@ export type AccessDecorator = (
 /**
  * Set whether a model property should be flattened or not.
  *
- * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters.
  * You can use "!" to specify negation such as "!(java, python)" or "!java, !python".
  * @example
  * ```typespec
@@ -376,7 +376,7 @@ export type FlattenPropertyDecorator = (
  *
  * @param original : The original service definition
  * @param override : The override method definition that specifies the exact client method you want
- * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters.
  * You can use "!" to specify negation such as "!(java, python)" or "!java, !python".
  * @example
  * ```typespec
@@ -427,7 +427,7 @@ export type OverrideDecorator = (
 /**
  * Whether a model needs the custom JSON converter, this is only used for backward compatibility for csharp.
  *
- * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters.
  * You can use "!" to specify negation such as "!(java, python)" or "!java, !python".
  * @example
  * ```typespec
@@ -446,7 +446,7 @@ export type UseSystemTextJsonConverterDecorator = (
 /**
  * Client parameters you would like to add to the client. By default, we apply endpoint, credential, and api-version parameters. If you add clientInitialization, we will append those to the default list of parameters.
  *
- * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters.
  * You can use "!" to specify negation such as "!(java, python)" or "!java, !python".
  * @example
  * ```typespec
@@ -477,7 +477,7 @@ export type ClientInitializationDecorator = (
 /**
  * Alias the name of a client parameter to a different name. This permits you to have a different name for the parameter in client initialization then on individual methods and still refer to the same parameter.
  *
- * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters.
  * You can use "!" to specify negation such as "!(java, python)" or "!java, !python".
  * @example
  * ```typespec
@@ -511,18 +511,19 @@ export type ParamAliasDecorator = (
  * By default, the client namespace for them will follow the TypeSpec namespace.
  *
  * @param rename The rename you want applied to the object
- * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters.
+ * You can use "!" to specify negation such as "!(java, python)" or "!java, !python".
  * @example
  * ```typespec
  * @clientNamespace("ContosoClient")
  * namespace Contoso;
  * ```
  * @example
  * ```typespec
- * @clientName("ContosoJava", "java")
- * @clientName("ContosoPython", "python")
- * @clientName("ContosoCSharp", "csharp")
- * @clientName("ContosoJavascript", "javascript")
+ * @clientNamespace("ContosoJava", "java")
+ * @clientNamespace("ContosoPython", "python")
+ * @clientNamespace("ContosoCSharp", "csharp")
+ * @clientNamespace("ContosoJavascript", "javascript")
  * namespace Contoso;
  * ```
  */
@@ -533,6 +534,32 @@ export type ClientNamespaceDecorator = (
   scope?: string,
 ) => void;
 
+/**
+ * Use to override default assumptions on whether a parameter is an api-version parameter or not.
+ * By default, we do matches with the `api-version` or `apiversion` string in the parameter name. Since api versions are
+ * a client parameter, we will also elevate this parameter up onto the client.
+ *
+ * @param value If true, we will treat this parameter as an api-version parameter. If false, we will not. Default is true.
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters.
+ * You can use "!" to specify negation such as "!(java, python)" or "!java, !python".
+ * @example
+ * ```typespec
+ * namespace Contoso;
+ *
+ * op test(
+ *   @apiVersion
+ *   @header("x-ms-version")
+ *   version: string
+ * ): void;
+ * ```
+ */
+export type ApiVersionDecorator = (
+  context: DecoratorContext,
+  target: ModelProperty,
+  value?: boolean,
+  scope?: string,
+) => void;
+
 export type AzureClientGeneratorCoreDecorators = {
   clientName: ClientNameDecorator;
   convenientAPI: ConvenientAPIDecorator;
@@ -547,4 +574,5 @@ export type AzureClientGeneratorCoreDecorators = {
   clientInitialization: ClientInitializationDecorator;
   paramAlias: ParamAliasDecorator;
   clientNamespace: ClientNamespaceDecorator;
+  apiVersion: ApiVersionDecorator;
 };
diff --git a/packages/typespec-client-generator-core/lib/decorators.tsp b/packages/typespec-client-generator-core/lib/decorators.tsp
@@ -5,7 +5,7 @@ namespace Azure.ClientGenerator.Core;
 /**
  * Changes the name of a method, parameter, property, or model generated in the client SDK
  * @param rename The rename you want applied to the object
- * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters.
  * You can use "!" to specify negation such as "!(java, python)" or "!java, !python".
  *
  * @example
@@ -28,7 +28,7 @@ extern dec clientName(target: unknown, rename: valueof string, scope?: valueof s
 /**
  * Whether you want to generate an operation as a convenient operation.
  * @param value Whether to generate the operation as convenience method or not.
- * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters.
  * You can use "!" to specify negation such as "!(java, python)" or "!java, !python".
  *
  * @example
@@ -42,7 +42,7 @@ extern dec convenientAPI(target: Operation, value?: valueof boolean, scope?: val
 /**
  * Whether you want to generate an operation as a protocol operation.
  * @param value Whether to generate the operation as protocol or not.
- * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters.
  * You can use "!" to specify negation such as "!(java, python)" or "!java, !python".
  *
  * @example
@@ -56,7 +56,7 @@ extern dec protocolAPI(target: Operation, value?: valueof boolean, scope?: value
 /**
  * Create a ClientGenerator.Core client out of a namespace or interface
  * @param value Optional configuration for the service.
- * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters.
  * You can use "!" to specify negation such as "!(java, python)" or "!java, !python".
  *
  * @example Basic client setting
@@ -85,7 +85,7 @@ extern dec client(target: Namespace | Interface, value?: Model, scope?: valueof
 
 /**
  * Create a ClientGenerator.Core operation group out of a namespace or interface
- * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters.
  * You can use "!" to specify negation such as "!(java, python)" or "!java, !python".
  *
  * @example
@@ -128,7 +128,7 @@ enum Usage {
  * and different override usage should not conflict with each other,
  * otherwise a warning will be added to diagnostics list.
  * @param value The usage info you want to set for this model.
- * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters.
  * You can use "!" to specify negation such as "!(java, python)" or "!java, !python".
  *
  * @example Expand usage for model
@@ -215,7 +215,7 @@ enum Access {
  * and different override access should not conflict with each other,
  * otherwise a warning will be added to diagnostics list.
  * @param value The access info you want to set for this model or operation.
- * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters.
  * You can use "!" to specify negation such as "!(java, python)" or "!java, !python".
  *
  * @example Set access
@@ -350,7 +350,7 @@ extern dec access(
 
 /**
  * Set whether a model property should be flattened or not.
- * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters.
  * You can use "!" to specify negation such as "!(java, python)" or "!java, !python".
  *
  * @example
@@ -370,7 +370,7 @@ extern dec flattenProperty(target: ModelProperty, scope?: valueof string);
  * Override the default client method generated by TCGC from your service definition
  * @param original: The original service definition
  * @param override: The override method definition that specifies the exact client method you want
- * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters.
  * You can use "!" to specify negation such as "!(java, python)" or "!java, !python".
  *
  * @example
@@ -417,7 +417,7 @@ extern dec override(original: Operation, override: Operation, scope?: valueof st
 
 /**
  * Whether a model needs the custom JSON converter, this is only used for backward compatibility for csharp.
- * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters.
  * You can use "!" to specify negation such as "!(java, python)" or "!java, !python".
  *
  * @example
@@ -432,7 +432,7 @@ extern dec useSystemTextJsonConverter(target: Model, scope?: valueof string);
 
 /**
  * Client parameters you would like to add to the client. By default, we apply endpoint, credential, and api-version parameters. If you add clientInitialization, we will append those to the default list of parameters.
- * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters.
  * You can use "!" to specify negation such as "!(java, python)" or "!java, !python".
  *
  * @example
@@ -462,7 +462,7 @@ extern dec clientInitialization(
 
 /**
  * Alias the name of a client parameter to a different name. This permits you to have a different name for the parameter in client initialization then on individual methods and still refer to the same parameter.
- * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters.
  * You can use "!" to specify negation such as "!(java, python)" or "!java, !python".
  *
  * @example
@@ -491,7 +491,8 @@ extern dec paramAlias(original: ModelProperty, paramAlias: valueof string, scope
  * Changes the namespace of a client, model, enum or union generated in the client SDK.
  * By default, the client namespace for them will follow the TypeSpec namespace.
  * @param rename The rename you want applied to the object
- * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters.
+ * You can use "!" to specify negation such as "!(java, python)" or "!java, !python".
  *
  * @example
  * ```typespec
@@ -501,10 +502,10 @@ extern dec paramAlias(original: ModelProperty, paramAlias: valueof string, scope
  *
  * @example
  * ```typespec
- * @clientName("ContosoJava", "java")
- * @clientName("ContosoPython", "python")
- * @clientName("ContosoCSharp", "csharp")
- * @clientName("ContosoJavascript", "javascript")
+ * @clientNamespace("ContosoJava", "java")
+ * @clientNamespace("ContosoPython", "python")
+ * @clientNamespace("ContosoCSharp", "csharp")
+ * @clientNamespace("ContosoJavascript", "javascript")
  * namespace Contoso;
  * ```
  */
@@ -513,3 +514,24 @@ extern dec clientNamespace(
   rename: valueof string,
   scope?: valueof string
 );
+
+/**
+ * Use to override default assumptions on whether a parameter is an api-version parameter or not.
+ * By default, we do matches with the `api-version` or `apiversion` string in the parameter name. Since api versions are
+ * a client parameter, we will also elevate this parameter up onto the client.
+ * @param value If true, we will treat this parameter as an api-version parameter. If false, we will not. Default is true.
+ * @param scope The language scope you want this decorator to apply to. If not specified, will apply to all language emitters.
+ * You can use "!" to specify negation such as "!(java, python)" or "!java, !python".
+ *
+ * @example
+ * ```typespec
+ * namespace Contoso;
+ *
+ * op test(
+ *   @apiVersion
+ *   @header("x-ms-version")
+ *   version: string
+ * ): void;
+ * ```
+ */
+extern dec apiVersion(target: ModelProperty, value?: valueof boolean, scope?: valueof string);