@azure-tools/typespec-ts 0.54.1 → 0.55.0-dev.2

package/src/transform/transform-parameters.ts

@@ -0,0 +1,321 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import {
+  SdkClient,
+  getHttpOperationWithCache,
+  isApiVersion,
+} from "@azure-tools/typespec-client-generator-core";
+import { NoTarget, Type, isVoidType } from "@typespec/compiler";
+import { HttpOperation, HttpOperationParameter, HttpOperationParameters } from "@typespec/http";
+import { reportDiagnostic } from "../lib.js";
+import {
+  ApiVersionInfo,
+  Imports,
+  ObjectSchema,
+  OperationParameter,
+  ParameterBodyMetadata,
+  ParameterMetadata,
+  Schema,
+  SchemaContext,
+} from "../rlc-common/index.js";
+import { listOperationsUnderRLCClient } from "../utils/client-utils.js";
+import { SdkContext } from "../utils/interfaces.js";
+import {
+  KnownMediaType,
+  extractMediaTypes,
+  hasMediaType,
+  isMediaTypeJsonMergePatch,
+} from "../utils/media-types.js";
+import {
+  getBodyType,
+  getCollectionFormat,
+  getFormattedPropertyDoc,
+  getImportedModelName,
+  getSchemaForType,
+  getTypeName,
+  isArrayType,
+  isBodyRequired,
+} from "../utils/model-utils.js";
+import {
+  getOperationGroupName,
+  getOperationName,
+  getSpecialSerializeInfo,
+} from "../utils/operation-util.js";
+import { getParameterSerializationInfo } from "../utils/parameter-utils.js";
+
+interface ParameterTransformationOptions {
+  apiVersionInfo?: ApiVersionInfo;
+  operationGroupName?: string;
+  operationName?: string;
+  importModels?: Set<string>;
+}
+
+export function transformToParameterTypes(
+  client: SdkClient,
+  dpgContext: SdkContext,
+  importDetails: Imports,
+  apiVersionInfo?: ApiVersionInfo,
+): OperationParameter[] {
+  const rlcParameters: OperationParameter[] = [];
+  const outputImportedSet = new Set<string>();
+  for (const op of listOperationsUnderRLCClient(client)) {
+    const route = getHttpOperationWithCache(dpgContext, op);
+    // ignore overload base operation
+    if (route.overloads && route.overloads?.length > 0) {
+      continue;
+    }
+    transformToParameterTypesForRoute(route);
+  }
+
+  if (outputImportedSet.size > 0) {
+    importDetails.parameter.importsSet = outputImportedSet;
+  }
+  function transformToParameterTypesForRoute(route: HttpOperation) {
+    const parameters = route.parameters;
+    const rlcParameter: OperationParameter = {
+      operationGroup: getOperationGroupName(dpgContext, route),
+      operationName: getOperationName(dpgContext, route.operation),
+      parameters: [],
+    };
+    const options = {
+      apiVersionInfo,
+      operationGroupName: rlcParameter.operationGroup,
+      operationName: rlcParameter.operationName,
+      importModels: outputImportedSet,
+    };
+    // transform query param
+    const queryParams = transformQueryParameters(dpgContext, parameters, options);
+    // transform path param
+    const pathParams = transformPathParameters(dpgContext, parameters, options);
+    // TODO: support cookie parameters, https://github.com/Azure/autorest.typescript/issues/2898
+    transformCookieParameters(dpgContext, parameters);
+    // transform header param including content-type
+    const headerParams = transformHeaderParameters(dpgContext, parameters, options);
+    // transform body
+    const bodyType = getBodyType(route);
+    let bodyParameter = undefined;
+    if (bodyType) {
+      bodyParameter = transformBodyParameters(
+        dpgContext,
+        parameters,
+        headerParams,
+        outputImportedSet,
+        bodyType,
+      );
+    }
+    rlcParameter.parameters.push({
+      parameters: [...queryParams, ...pathParams, ...headerParams],
+      body: bodyParameter,
+    });
+    rlcParameters.push(rlcParameter);
+  }
+  return rlcParameters;
+}
+
+function getParameterMetadata(
+  dpgContext: SdkContext,
+  paramType: "query" | "path" | "header",
+  parameter: HttpOperationParameter,
+  options: ParameterTransformationOptions,
+): ParameterMetadata {
+  const program = dpgContext.program;
+  const importedModels = options.importModels ?? new Set<string>();
+  const schemaContext = [SchemaContext.Exception, SchemaContext.Input];
+  const schema = getSchemaForType(dpgContext, parameter.param.type, {
+    usage: schemaContext,
+    needRef: false,
+    relevantProperty: parameter.param,
+  }) as Schema;
+  const name = getParameterName(parameter.name);
+  let description = getFormattedPropertyDoc(program, parameter.param, schema) ?? "";
+  const format = getCollectionFormat(dpgContext, parameter as any);
+  if (isArrayType(schema) && format) {
+    const serializeInfo = getSpecialSerializeInfo(dpgContext, parameter.type, format);
+    if (serializeInfo.hasMultiCollection || serializeInfo.hasCsvCollection) {
+      description += `${description ? "\n" : ""}This parameter could be formatted as ${serializeInfo.collectionInfo.join(
+        ", ",
+      )} collection string, we provide ${serializeInfo.descriptions.join(
+        ", ",
+      )} from serializeHelper.ts to help${
+        serializeInfo.hasMultiCollection
+          ? ", you will probably need to set skipUrlEncoding as true when sending the request"
+          : ""
+      }.`;
+    }
+    if (format === "tsv") {
+      description += `${description ? "\n" : ""}This parameter could be formatted as tsv collection string.`;
+    }
+  }
+
+  getImportedModelName(schema, schemaContext)?.forEach(importedModels.add, importedModels);
+  const serializationType = getParameterSerializationInfo(
+    dpgContext,
+    parameter,
+    schema,
+    options.operationGroupName,
+    options.operationName,
+  );
+  return {
+    type: paramType,
+    name,
+    param: {
+      name,
+      type: serializationType.typeName,
+      typeName: serializationType.typeName,
+      required: !parameter.param.optional,
+      description,
+      wrapperType: serializationType.wrapperType,
+    },
+  };
+}
+
+function getParameterName(name: string) {
+  if (name && name.toLowerCase() === "content-type") {
+    return "contentType";
+  }
+  return `"${name}"`;
+}
+
+function transformCookieParameters(dpgContext: SdkContext, parameters: HttpOperationParameters) {
+  // TODO: support cookie parameters, https://github.com/Azure/autorest.typescript/issues/2898
+  parameters.parameters
+    .filter((p) => p.type === "cookie")
+    .forEach((p) => {
+      reportDiagnostic(dpgContext.program, {
+        code: "parameter-type-not-supported",
+        format: {
+          paramName: p.name,
+          paramType: p.type,
+        },
+        target: NoTarget,
+      });
+    });
+}
+
+function transformQueryParameters(
+  dpgContext: SdkContext,
+  parameters: HttpOperationParameters,
+  options: ParameterTransformationOptions,
+): ParameterMetadata[] {
+  const queryParameters = parameters.parameters.filter(
+    (p) =>
+      p.type === "query" &&
+      !(isApiVersion(dpgContext, p.param) && options.apiVersionInfo?.definedPosition === "query"),
+  );
+  if (!queryParameters.length) {
+    return [];
+  }
+  return queryParameters.map((qp) => getParameterMetadata(dpgContext, "query", qp, options));
+}
+
+/**
+ * Only support to take the global path parameter as path parameter
+ * @returns
+ */
+function transformPathParameters(
+  dpgContext: SdkContext,
+  parameters: HttpOperationParameters,
+  options: ParameterTransformationOptions,
+) {
+  // build wrapper path parameters
+  const pathParameters = parameters.parameters.filter((p) => p.type === "path");
+  if (!pathParameters.length) {
+    return [];
+  }
+  // only need to build path parameters for wrapper type
+  const params = pathParameters
+    .map((qp) => getParameterMetadata(dpgContext, "path", qp, options))
+    .filter((p) => p.param.wrapperType);
+  return params;
+}
+
+export function transformHeaderParameters(
+  dpgContext: SdkContext,
+  parameters: HttpOperationParameters,
+  options: ParameterTransformationOptions,
+): ParameterMetadata[] {
+  const headerParameters = parameters.parameters.filter((p) => p.type === "header");
+  if (!headerParameters.length) {
+    return [];
+  }
+  return headerParameters.map((qp) => getParameterMetadata(dpgContext, "header", qp, options));
+}
+
+function transformBodyParameters(
+  dpgContext: SdkContext,
+  parameters: HttpOperationParameters,
+  headers: ParameterMetadata[],
+  importedModels: Set<string>,
+  inputBodyType?: Type,
+): ParameterBodyMetadata | undefined {
+  const bodyType = parameters.body && inputBodyType ? inputBodyType : parameters.body?.type;
+  if (!bodyType || isVoidType(bodyType)) {
+    return;
+  }
+  return transformRequestBody(dpgContext, bodyType, parameters, importedModels, headers);
+}
+
+function transformRequestBody(
+  dpgContext: SdkContext,
+  bodyType: Type,
+  parameters: HttpOperationParameters,
+  importedModels: Set<string>,
+  headers: ParameterMetadata[],
+) {
+  const contentTypes = extractMediaTypes(parameters.body?.contentTypes ?? []);
+  const schema = getSchemaForType(dpgContext, bodyType, {
+    mediaTypes: contentTypes,
+    isRequestBody: true,
+    usage: [SchemaContext.Input, SchemaContext.Exception],
+  });
+
+  const descriptions = getBodyDescriptions(dpgContext, schema, parameters);
+  const type = getRequestBodyType(schema, importedModels, headers);
+
+  return {
+    isPartialBody: false,
+    body: [
+      {
+        properties: schema.properties,
+        typeName: schema.name,
+        name: "body",
+        type,
+        required: isBodyRequired(parameters),
+        description: descriptions.join("\n\n"),
+        isMultipartBody:
+          hasMediaType(KnownMediaType.MultipartFormData, contentTypes) && contentTypes.length === 1,
+        oriSchema: schema,
+      },
+    ],
+  };
+}
+
+function getRequestBodyType(
+  bodySchema: Schema,
+  importedModels: Set<string>,
+  headers?: ParameterMetadata[],
+) {
+  const schemaUsage = [SchemaContext.Input, SchemaContext.Exception];
+  const importedNames = getImportedModelName(bodySchema, schemaUsage) ?? [];
+  importedNames.forEach(importedModels.add, importedModels);
+
+  let typeName = getTypeName(bodySchema, schemaUsage);
+  const contentTypes = headers?.filter((h) => h.name === "contentType").map((h) => h.param.type);
+  const hasMergeAndPatchType = isMediaTypeJsonMergePatch(contentTypes ?? []);
+  if (hasMergeAndPatchType && Boolean(bodySchema.name) && (bodySchema as ObjectSchema).properties) {
+    typeName = `${typeName}ResourceMergeAndPatch`;
+  }
+  return typeName;
+}
+
+function getBodyDescriptions(
+  dpgContext: SdkContext,
+  bodySchema: Schema,
+  parameters: HttpOperationParameters,
+) {
+  const description = parameters.body?.property
+    ? getFormattedPropertyDoc(dpgContext.program, parameters.body.property, bodySchema)
+    : "";
+  return description ? [description] : [];
+}

package/src/transform/transform-paths.ts

@@ -0,0 +1,157 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import {
+  SdkClient,
+  getHttpOperationWithCache,
+  isApiVersion,
+} from "@azure-tools/typespec-client-generator-core";
+import { HttpOperation, HttpOperationParameters } from "@typespec/http";
+import {
+  Imports,
+  OperationMethod,
+  PathMetadata,
+  Paths,
+  SchemaContext,
+  getParameterTypeName,
+  getResponseTypeName,
+} from "../rlc-common/index.js";
+import { getImportedModelName, getSchemaForType, isBodyRequired } from "../utils/model-utils.js";
+import {
+  extractOperationLroDetail,
+  getOperationGroupName,
+  getOperationName,
+  getOperationResponseTypes,
+  getOperationStatuscode,
+  getOperationSuccessStatus,
+  isPagingOperation,
+  sortedOperationResponses,
+} from "../utils/operation-util.js";
+
+import { getDoc } from "@typespec/compiler";
+import { listOperationsUnderRLCClient } from "../utils/client-utils.js";
+import { SdkContext } from "../utils/interfaces.js";
+import { getParameterSerializationInfo } from "../utils/parameter-utils.js";
+
+export function transformPaths(
+  client: SdkClient,
+  dpgContext: SdkContext,
+  importDetails: Imports,
+): Paths {
+  const pathParamsImportedSet = new Set<string>();
+  const paths: Paths = {};
+  for (const op of listOperationsUnderRLCClient(client)) {
+    const route = getHttpOperationWithCache(dpgContext, op);
+    // ignore overload base operation
+    if (route.overloads && route.overloads?.length > 0) {
+      continue;
+    }
+    transformOperation(dpgContext, route, paths, pathParamsImportedSet);
+  }
+
+  if (pathParamsImportedSet.size > 0) {
+    importDetails.rlcClientDefinition.importsSet = pathParamsImportedSet;
+  }
+
+  return paths;
+}
+
+function transformOperation(
+  dpgContext: SdkContext,
+  route: HttpOperation,
+  paths: Paths,
+  importSet: Set<string>,
+) {
+  const program = dpgContext.program;
+  const respNames = [];
+  const operationGroupName = getOperationGroupName(dpgContext, route);
+  for (const resp of sortedOperationResponses(route.responses)) {
+    const respName = getResponseTypeName(
+      operationGroupName,
+      getOperationName(dpgContext, route.operation),
+      getOperationStatuscode(resp),
+    );
+    respNames.push(respName);
+  }
+  const responseTypes = getOperationResponseTypes(dpgContext, route);
+  const method: OperationMethod = {
+    description: getDoc(program, route.operation) ?? "",
+    hasOptionalOptions: !hasRequiredOptions(dpgContext, route.parameters),
+    optionsName: getParameterTypeName(
+      operationGroupName,
+      getOperationName(dpgContext, route.operation),
+    ),
+    responseTypes,
+    returnType: respNames.join(" | "),
+    successStatus: getOperationSuccessStatus(route),
+    operationName: getOperationName(dpgContext, route.operation),
+    operationHelperDetail: {
+      lroDetails: extractOperationLroDetail(dpgContext, route, responseTypes, operationGroupName),
+      isPaging: isPagingOperation(dpgContext, route),
+    },
+  };
+  if (paths[route.path] !== undefined && !paths[route.path]?.methods[route.verb]) {
+    (paths[route.path] as PathMetadata).methods[route.verb] = [method];
+  } else if (paths[route.path]?.methods[route.verb]) {
+    paths[route.path]?.methods[route.verb]?.push(method);
+  } else {
+    paths[route.path] = {
+      description: getDoc(program, route.operation) ?? "",
+      name: escapeCoreName(getOperationName(dpgContext, route.operation) || "Client"),
+      pathParameters: route.parameters.parameters
+        .filter((p) => p.type === "path")
+        .map((p) => {
+          const schemaUsage = [SchemaContext.Input, SchemaContext.Exception];
+          const options = {
+            usage: schemaUsage,
+            needRef: false,
+            relevantProperty: p.param,
+          };
+          const schema = p.param.sourceProperty
+            ? getSchemaForType(
+                dpgContext,
+                p.param.sourceProperty?.type,
+
+                options,
+              )
+            : getSchemaForType(dpgContext, p.param.type, options);
+          const importedNames = getImportedModelName(schema, schemaUsage) ?? [];
+          importedNames.forEach(importSet.add, importSet);
+          const serializationType = getParameterSerializationInfo(
+            dpgContext,
+            p,
+            schema,
+            operationGroupName,
+            method.operationName,
+          );
+          return {
+            name: p.name,
+            type: serializationType.typeName,
+            description: getDoc(program, p.param) ?? "",
+            wrapperType: serializationType.wrapperType,
+          };
+        }),
+      operationGroupName: getOperationGroupName(dpgContext, route),
+      methods: {
+        [route.verb]: [method],
+      },
+    };
+  }
+}
+
+function escapeCoreName(name: string) {
+  if (["client", "streamablemethod"].indexOf(name.toLowerCase()) > -1) {
+    return "_" + name;
+  }
+  return name;
+}
+function hasRequiredOptions(dpgContext: SdkContext, routeParameters: HttpOperationParameters) {
+  const isRequiredBodyParam = isBodyRequired(routeParameters);
+
+  const containsRequiredNonBodyParam = routeParameters.parameters
+    .filter((parameter) => ["query", "header"].includes(parameter.type))
+    .filter((parameter) => !isApiVersion(dpgContext, parameter.param))
+    .filter((parameter) => !!parameter.param)
+    .some((parameter) => parameter.param.optional === false);
+  return isRequiredBodyParam || containsRequiredNonBodyParam;
+}

package/src/transform/transform-responses.ts

@@ -0,0 +1,237 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { getHttpOperationWithCache, SdkClient } from "@azure-tools/typespec-client-generator-core";
+import { getDoc, isVoidType } from "@typespec/compiler";
+import { HttpOperation, HttpOperationResponse } from "@typespec/http";
+import {
+  getLroLogicalResponseName,
+  Imports,
+  OperationResponse,
+  ResponseHeaderSchema,
+  ResponseMetadata,
+  Schema,
+  SchemaContext,
+} from "../rlc-common/index.js";
+import { listOperationsUnderRLCClient } from "../utils/client-utils.js";
+import { SdkContext } from "../utils/interfaces.js";
+import {
+  getBinaryType,
+  getImportedModelName,
+  getSchemaForType,
+  getTypeName,
+} from "../utils/model-utils.js";
+import {
+  getOperationGroupName,
+  getOperationLroOverload,
+  getOperationName,
+  getOperationStatuscode,
+  isBinaryPayload,
+  sortedOperationResponses,
+} from "../utils/operation-util.js";
+
+export function transformToResponseTypes(
+  client: SdkClient,
+  dpgContext: SdkContext,
+  importDetails: Imports,
+): OperationResponse[] {
+  const rlcResponses: OperationResponse[] = [];
+  const inputImportedSet = new Set<string>();
+  for (const op of listOperationsUnderRLCClient(client)) {
+    const route = getHttpOperationWithCache(dpgContext, op);
+    // ignore overload base operation
+    if (route.overloads && route.overloads?.length > 0) {
+      continue;
+    }
+    transformToResponseTypesForRoute(route);
+  }
+  if (inputImportedSet.size > 0) {
+    importDetails.response.importsSet = inputImportedSet;
+  }
+  function transformToResponseTypesForRoute(route: HttpOperation) {
+    const rlcOperationUnit: OperationResponse = {
+      operationGroup: getOperationGroupName(dpgContext, route),
+      operationName: getOperationName(dpgContext, route.operation),
+      path: route.path,
+      responses: [],
+    };
+    const defaultSchemas: Schema[] = [],
+      nonDefaultSchemas: Schema[] = [];
+    for (const resp of sortedOperationResponses(route.responses)) {
+      const statusCode = getOperationStatuscode(resp);
+      const rlcResponseUnit: ResponseMetadata = {
+        statusCode,
+        description: resp.description,
+      };
+      // transform header
+      const headers = transformHeaders(dpgContext, resp, inputImportedSet);
+      // transform body
+      const [body, schemas] = transformBody(dpgContext, resp, inputImportedSet) ?? [undefined, []];
+      rlcOperationUnit.responses.push({
+        ...rlcResponseUnit,
+        headers,
+        body,
+      });
+      if (statusCode === "default") {
+        defaultSchemas.push(...schemas);
+      } else {
+        nonDefaultSchemas.push(...schemas);
+      }
+    }
+    const lroLogicalResponse = transformLroLogicalResponse(
+      dpgContext,
+      route,
+      getOperationGroupName(dpgContext, route),
+      rlcOperationUnit.responses,
+    );
+    if (lroLogicalResponse) {
+      rlcOperationUnit.responses.push(lroLogicalResponse);
+    }
+    rlcResponses.push(rlcOperationUnit);
+  }
+  return rlcResponses;
+}
+
+/**
+ * Return undefined if no valid header param
+ * @param response response detail
+ * @returns rlc header schema
+ */
+function transformHeaders(
+  dpgContext: SdkContext,
+  response: HttpOperationResponse,
+  importedModels: Set<string>,
+): ResponseHeaderSchema[] | undefined {
+  if (!response.responses.length) {
+    return;
+  }
+
+  const rlcHeaders: Map<string, ResponseHeaderSchema> = new Map();
+  // Current RLC client can't represent different headers per content type.
+  // So we merge headers here, and report any duplicates.
+  // It may be possible in principle to not error for identically declared
+  // headers.
+  for (const data of response.responses) {
+    const headers = data?.headers ?? {};
+    if (data.body?.contentTypeProperty) {
+      headers["content-type"] = data.body?.contentTypeProperty;
+    }
+    if (!headers || !Object.keys(headers).length) {
+      continue;
+    }
+
+    for (const [key, value] of Object.entries(headers)) {
+      if (!value) {
+        continue;
+      }
+      const typeSchema = getSchemaForType(dpgContext, value!.type, {
+        usage: [SchemaContext.Output],
+        relevantProperty: value,
+      }) as Schema;
+      const type = getTypeName(typeSchema, [SchemaContext.Output]);
+      getImportedModelName(typeSchema, [SchemaContext.Output])?.forEach(
+        importedModels.add,
+        importedModels,
+      );
+      const header: ResponseHeaderSchema = {
+        name: `"${key.toLowerCase()}"`,
+        type,
+        required: !value?.optional,
+        description: getDoc(dpgContext.program, value!),
+      };
+      rlcHeaders.set(header.name, header);
+    }
+  }
+
+  return rlcHeaders.size ? Array.from(rlcHeaders.values()) : undefined;
+}
+
+function transformBody(
+  dpgContext: SdkContext,
+  response: HttpOperationResponse,
+  importedModels: Set<string>,
+): [Schema, Schema[]] | undefined {
+  if (!response.responses.length) {
+    return;
+  }
+  // Currently RLC response only have one header and body defined
+  // So we'll union all body shapes together with "|"
+  const typeSet = new Set<string>();
+  const descriptions = new Set<string>();
+  let fromCore = false;
+  const schemas = [];
+  for (const data of response.responses) {
+    const body = data?.body;
+    if (!body || isVoidType(body.type)) {
+      continue;
+    }
+    const hasBinaryContent = body.contentTypes.some((contentType) =>
+      isBinaryPayload(dpgContext, body.type, contentType),
+    );
+    if (hasBinaryContent) {
+      typeSet.add(getBinaryType([SchemaContext.Output]));
+      descriptions.add("Value may contain any sequence of octets");
+      continue;
+    }
+    const bodySchema = getSchemaForType(dpgContext, body!.type, {
+      usage: [SchemaContext.Output],
+    }) as Schema;
+    fromCore = bodySchema.fromCore ?? false;
+    const bodyType = getTypeName(bodySchema);
+    const importedNames = getImportedModelName(bodySchema);
+    if (importedNames && !fromCore) {
+      importedNames
+        .filter((name) => {
+          return name !== "any";
+        })
+        .forEach(importedModels.add, importedModels);
+    }
+    typeSet.add(bodyType);
+    schemas.push(bodySchema);
+  }
+
+  if (!typeSet.size) {
+    return;
+  }
+
+  return [
+    {
+      name: "body",
+      type: [...typeSet].join("|"),
+      description: [...descriptions].join("\n\n"),
+      fromCore,
+    },
+    schemas,
+  ];
+}
+
+function transformLroLogicalResponse(
+  dpgContext: SdkContext,
+  route: HttpOperation,
+  operationGroupName: string,
+  existingResponses: ResponseMetadata[],
+): ResponseMetadata | undefined {
+  const operationLroOverload = getOperationLroOverload(
+    dpgContext.program,
+    route,
+    undefined,
+    existingResponses,
+  );
+  if (!operationLroOverload) {
+    return;
+  }
+  const sortedResponses = existingResponses
+    .filter((r) => r.statusCode.startsWith("20"))
+    .sort((r1, r2) => (r1.statusCode > r2.statusCode ? 1 : -1));
+  const successResp = sortedResponses[0];
+  const logicalLROResponse: ResponseMetadata = {
+    statusCode: "200",
+    description: `The final response for long-running ${route.operation.name} operation`,
+    predefinedName: getLroLogicalResponseName(
+      operationGroupName,
+      getOperationName(dpgContext, route.operation),
+    ),
+    body: successResp?.body,
+  };
+  return logicalLROResponse;
+}