Feature: Override shared param description (#4318)

common/changes/@autorest/modelerfour/feature-override-shared-param-description_2021-10-01-18-41.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@autorest/modelerfour",
+      "comment": "**Added** Support for overriding shared param description",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@autorest/modelerfour",
+  "email": "tiguerin@microsoft.com"
+}

common/changes/@azure-tools/openapi/feature-override-shared-param-description_2021-10-01-18-42.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@azure-tools/openapi",
+      "comment": "Tweak types for description next to parameter",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@azure-tools/openapi",
+  "email": "tiguerin@microsoft.com"
+}

packages/extensions/modelerfour/src/modeler/modelerfour.ts

@@ -1963,7 +1963,7 @@ export class ModelerFour {
 
   processParameters(httpOperation: OpenAPI.HttpOperation, operation: Operation, pathItem: OpenAPI.PathItem) {
     const parameters = Object.values(httpOperation.parameters ?? {})
-      .map((each) => dereference(this.input, each))
+      .map((x) => ({ ...dereference<OpenAPI.Parameter>(this.input, x), original: x }))
       .filter((x) => !this.isParameterIgnoredHeader(x.instance));
 
     for (const pp of parameters) {
@@ -1983,10 +1983,10 @@ export class ModelerFour {
 
         // Not an APIVersion Parameter
         const implementation = pp.fromRef
-          ? "method" === <any>parameter["x-ms-parameter-location"]
+          ? "method" === parameter["x-ms-parameter-location"]
             ? ImplementationLocation.Method
             : ImplementationLocation.Client
-          : "client" === <any>parameter["x-ms-parameter-location"]
+          : "client" === parameter["x-ms-parameter-location"]
           ? ImplementationLocation.Client
           : ImplementationLocation.Method;
 
@@ -2015,9 +2015,10 @@ export class ModelerFour {
           parameterSchema = dictionarySchema;
         }
 
+        const description = pp.original.description || this.interpret.getDescription("", parameter);
         /* regular, everyday parameter */
         const newParam = operation.addParameter(
-          new Parameter(preferredName, this.interpret.getDescription("", parameter), parameterSchema, {
+          new Parameter(preferredName, description, parameterSchema, {
             required: parameter.required ? true : undefined,
             implementation,
             extensions: this.interpret.getExtensionProperties(parameter),

packages/libs/openapi/src/oai3.ts

@@ -24,7 +24,10 @@ export interface PropertyDetails extends Details, Extensions {
   description?: string;
 }
 
-export interface ParameterDetails extends Details {}
+/** Parameter References may have additional data that's not in the target reference */
+export interface ParameterDetails extends Details, Extensions {
+  description?: string;
+}
 
 export interface SchemaDetails extends Details {}
 
@@ -67,9 +70,16 @@ export function isQueryParameter(parameter: Parameter): parameter is InQuery & P
   return parameter.in === ParameterLocation.Query ? true : false;
 }
 
-/** Properties have additional data when referencing them */
+/**
+ * Properties have additional data when referencing them
+ */
 export type PropertyReference<T> = PropertyDetails & Reference<T>;
 
+/**
+ * Parameter references could have additional data to override the shared parameter value.
+ */
+export type ParameterReference<T> = ParameterDetails & Reference<T>;
+
 /**
  * @description common ways of serializing simple parameters
  * @see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#style-values
@@ -269,7 +279,7 @@ export interface HttpOperation extends Deprecatable, Extensions, Implementation<
   description?: string;
   externalDocs?: ExternalDocumentation;
   operationId?: string;
-  parameters?: Array<Reference<Parameter>>;
+  parameters?: ParameterReference<Parameter>[];
   requestBody?: Reference<RequestBody>;
   responses: Dictionary<Reference<Response>>;
   callbacks?: Dictionary<Reference<Callback>>;
@@ -348,8 +358,8 @@ export interface PathItem extends Extensions {
   head?: HttpOperation;
   patch?: HttpOperation;
   trace?: HttpOperation;
-  servers?: Array<Server>;
-  parameters?: Array<Reference<Parameter>>;
+  servers?: Server[];
+  parameters?: ParameterReference<Parameter>[];
 }
 
 export interface RequestBody extends Extensions {