From e4d28e3a869f946871525ab891104665c3061aac Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Fri, 1 Oct 2021 14:42:12 -0700 Subject: [PATCH] Feature: Override shared param description (#4318) --- ...ed-param-description_2021-10-01-18-41.json | 11 ++++++++++ ...ed-param-description_2021-10-01-18-42.json | 11 ++++++++++ .../modelerfour/src/modeler/modelerfour.ts | 9 +++++---- packages/libs/openapi/src/oai3.ts | 20 ++++++++++++++----- 4 files changed, 42 insertions(+), 9 deletions(-) create mode 100644 common/changes/@autorest/modelerfour/feature-override-shared-param-description_2021-10-01-18-41.json create mode 100644 common/changes/@azure-tools/openapi/feature-override-shared-param-description_2021-10-01-18-42.json diff --git a/common/changes/@autorest/modelerfour/feature-override-shared-param-description_2021-10-01-18-41.json b/common/changes/@autorest/modelerfour/feature-override-shared-param-description_2021-10-01-18-41.json new file mode 100644 index 000000000..08127ac8a --- /dev/null +++ b/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" +} \ No newline at end of file diff --git a/common/changes/@azure-tools/openapi/feature-override-shared-param-description_2021-10-01-18-42.json b/common/changes/@azure-tools/openapi/feature-override-shared-param-description_2021-10-01-18-42.json new file mode 100644 index 000000000..8b3e341f8 --- /dev/null +++ b/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" +} \ No newline at end of file diff --git a/packages/extensions/modelerfour/src/modeler/modelerfour.ts b/packages/extensions/modelerfour/src/modeler/modelerfour.ts index 6e165de73..c5f819f48 100644 --- a/packages/extensions/modelerfour/src/modeler/modelerfour.ts +++ b/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(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" === parameter["x-ms-parameter-location"] + ? "method" === parameter["x-ms-parameter-location"] ? ImplementationLocation.Method : ImplementationLocation.Client - : "client" === 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), diff --git a/packages/libs/openapi/src/oai3.ts b/packages/libs/openapi/src/oai3.ts index ae81845a2..a94ba2284 100644 --- a/packages/libs/openapi/src/oai3.ts +++ b/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 = PropertyDetails & Reference; +/** + * Parameter references could have additional data to override the shared parameter value. + */ +export type ParameterReference = ParameterDetails & Reference; + /** * @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>; + parameters?: ParameterReference[]; requestBody?: Reference; responses: Dictionary>; callbacks?: Dictionary>; @@ -348,8 +358,8 @@ export interface PathItem extends Extensions { head?: HttpOperation; patch?: HttpOperation; trace?: HttpOperation; - servers?: Array; - parameters?: Array>; + servers?: Server[]; + parameters?: ParameterReference[]; } export interface RequestBody extends Extensions {