@azure-tools/typespec-autorest 0.43.0-dev.1 → 0.43.0-dev.11

package/dist/src/openapi.js

@@ -1,6 +1,7 @@
-import { extractLroStates, getArmResourceIdentifierConfig, getAsEmbeddingVector, getLroMetadata, getPagedResult, getUnionAsEnum, isFixed, } from "@azure-tools/typespec-azure-core";
+import { FinalStateValue, extractLroStates, getArmResourceIdentifierConfig, getAsEmbeddingVector, getLroMetadata, getPagedResult, getUnionAsEnum, } from "@azure-tools/typespec-azure-core";
+import { getArmCommonTypeOpenAPIRef, isArmCommonType, } from "@azure-tools/typespec-azure-resource-manager";
 import { shouldFlattenProperty } from "@azure-tools/typespec-client-generator-core";
-import { NoTarget, SyntaxKind, compilerAssert, createDiagnosticCollector, getAllTags, getDirectoryPath, getDiscriminator, getDoc, getEncode, getFormat, getKnownValues, getMaxItems, getMaxLength, getMaxValue, getMinItems, getMinLength, getMinValue, getPattern, getProjectedName, getProperty, getPropertyType, getRelativePathFromDirectory, getRootLength, getSummary, getVisibility, ignoreDiagnostics, interpolatePath, isArrayModelType, isDeprecated, isErrorModel, isErrorType, isGlobalNamespace, isNeverType, isNullType, isNumericType, isRecordModelType, isSecret, isService, isStringType, isTemplateDeclaration, isTemplateDeclarationOrInstance, isVoidType, navigateTypesInNamespace, resolveEncodedName, resolvePath, stringTemplateToString, } from "@typespec/compiler";
+import { NoTarget, SyntaxKind, compilerAssert, createDiagnosticCollector, explainStringTemplateNotSerializable, getAllTags, getDirectoryPath, getDiscriminator, getDoc, getEncode, getFormat, getKnownValues, getMaxItems, getMaxLength, getMaxValue, getMinItems, getMinLength, getMinValue, getPattern, getProjectedName, getProperty, getPropertyType, getRelativePathFromDirectory, getRootLength, getSummary, getVisibility, ignoreDiagnostics, interpolatePath, isArrayModelType, isDeprecated, isErrorModel, isErrorType, isGlobalNamespace, isNeverType, isNullType, isNumericType, isRecordModelType, isSecret, isService, isStringType, isTemplateDeclaration, isTemplateDeclarationOrInstance, isVoidType, navigateTypesInNamespace, resolveEncodedName, resolvePath, } from "@typespec/compiler";
 import { TwoLevelMap } from "@typespec/compiler/utils";
 import { Visibility, createMetadataInfo, getAllHttpServices, getAuthentication, getHeaderFieldOptions, getQueryParamOptions, getServers, getStatusCodeDescription, getVisibilitySuffix, isContentTypeHeader, isSharedRoute, reportIfNoRoutes, resolveRequestVisibility, } from "@typespec/http";
 import { checkDuplicateTypeName, getExtensions, getExternalDocs, getOpenAPITypeName, getParameterKey, isReadonlyProperty, resolveInfo, shouldInline, } from "@typespec/openapi";
@@ -126,6 +127,7 @@ export async function getOpenAPIForService(context, options) {
             }
         })
             .filter((x) => x),
+        outputFile: context.outputFile,
     };
     function resolveHost(program, namespace) {
         const servers = getServers(program, namespace);
@@ -238,6 +240,40 @@ export async function getOpenAPIForService(context, options) {
         // strip everything from the key including and after the ?
         return path.replace(/\/?\?.*/, "");
     }
+    function getFinalStateVia(metadata) {
+        switch (metadata.finalStateVia) {
+            case FinalStateValue.azureAsyncOperation:
+                return "azure-async-operation";
+            case FinalStateValue.location:
+                return "location";
+            case FinalStateValue.operationLocation:
+                return "operation-location";
+            case FinalStateValue.originalUri:
+                return "original-uri";
+            default:
+                return undefined;
+        }
+    }
+    function getFinalStateSchema(metadata) {
+        if (metadata.finalResult !== undefined &&
+            metadata.finalResult !== "void" &&
+            metadata.finalResult.name.length > 0) {
+            const model = metadata.finalResult;
+            const schemaOrRef = resolveExternalRef(metadata.finalResult);
+            if (schemaOrRef !== undefined) {
+                const ref = new Ref();
+                ref.value = schemaOrRef.$ref;
+                return { "final-state-schema": ref };
+            }
+            const pending = pendingSchemas.getOrAdd(metadata.finalResult, Visibility.Read, () => ({
+                type: model,
+                visibility: Visibility.Read,
+                ref: refs.getOrAdd(model, Visibility.Read, () => new Ref()),
+            }));
+            return { "final-state-schema": pending.ref };
+        }
+        return undefined;
+    }
     function emitOperation(operation) {
         let { path: fullPath, operation: op, verb, parameters } = operation;
         let pathsObject = root.paths;
@@ -294,6 +330,22 @@ export async function getOpenAPIForService(context, options) {
         // which does have LRO metadata.
         if (lroMetadata !== undefined && operation.verb !== "get") {
             currentEndpoint["x-ms-long-running-operation"] = true;
+            if (options.emitLroOptions !== "none") {
+                const finalState = getFinalStateVia(lroMetadata);
+                if (finalState !== undefined) {
+                    const finalSchema = getFinalStateSchema(lroMetadata);
+                    let lroOptions = {
+                        "final-state-via": finalState,
+                    };
+                    if (finalSchema !== undefined && options.emitLroOptions === "all") {
+                        lroOptions = {
+                            "final-state-via": finalState,
+                            ...finalSchema,
+                        };
+                    }
+                    currentEndpoint["x-ms-long-running-operation-options"] = lroOptions;
+                }
+            }
         }
         // Extract paged metadata from Azure.Core.Page
         extractPagedMetadata(program, operation);
@@ -442,19 +494,27 @@ export async function getOpenAPIForService(context, options) {
             }
         }
         if (body) {
-            const isBinary = contentTypes.every((t) => isBinaryPayload(body.type, t));
-            openapiResponse.schema = isBinary
-                ? { type: "file" }
-                : getSchemaOrRef(body.type, {
-                    visibility: Visibility.Read,
-                    ignoreMetadataAnnotations: body.isExplicit && body.containsMetadataAnnotations,
-                });
+            openapiResponse.schema = getSchemaForResponseBody(body, contentTypes);
         }
         for (const contentType of contentTypes) {
             currentProduces.add(contentType);
         }
         currentEndpoint.responses[statusCode] = openapiResponse;
     }
+    function getSchemaForResponseBody(body, contentTypes) {
+        const isBinary = contentTypes.every((t) => isBinaryPayload(body.type, t));
+        if (isBinary) {
+            return { type: "file" };
+        }
+        if (body.bodyKind === "multipart") {
+            // OpenAPI2 doesn't support multipart responses, so we just return a string schema
+            return { type: "string" };
+        }
+        return getSchemaOrRef(body.type, {
+            visibility: Visibility.Read,
+            ignoreMetadataAnnotations: body.isExplicit && body.containsMetadataAnnotations,
+        });
+    }
     function getResponseHeader(prop) {
         const header = {};
         populateParameter(header, prop, "header", {
@@ -466,7 +526,7 @@ export async function getOpenAPIForService(context, options) {
         delete header.required;
         return header;
     }
-    function resolveRef(ref) {
+    function expandRef(ref) {
         const absoluteRef = interpolatePath(ref, {
             "arm-types-dir": options.armTypesDir,
         });
@@ -475,13 +535,31 @@ export async function getOpenAPIForService(context, options) {
         }
         return getRelativePathFromDirectory(getDirectoryPath(context.outputFile), absoluteRef, false);
     }
-    function getSchemaOrRef(type, schemaContext) {
-        const refUrl = getRef(program, type, { version: context.version, service: context.service });
+    function resolveExternalRef(type) {
+        const refUrl = getRef(program, type);
         if (refUrl) {
             return {
-                $ref: resolveRef(refUrl),
+                $ref: expandRef(refUrl),
             };
         }
+        if (isArmCommonType(type) && (type.kind === "Model" || type.kind === "ModelProperty")) {
+            const ref = getArmCommonTypeOpenAPIRef(program, type, {
+                version: context.version,
+                service: context.service,
+            });
+            if (ref) {
+                return {
+                    $ref: expandRef(ref),
+                };
+            }
+        }
+        return undefined;
+    }
+    function getSchemaOrRef(type, schemaContext) {
+        const ref = resolveExternalRef(type);
+        if (ref) {
+            return ref;
+        }
         if (type.kind === "Scalar" && program.checker.isStdType(type)) {
             return getSchemaForScalar(type);
         }
@@ -560,14 +638,9 @@ export async function getOpenAPIForService(context, options) {
                 property = property.sourceProperty;
             }
         }
-        const refUrl = getRef(program, property, {
-            version: context.version,
-            service: context.service,
-        });
-        if (refUrl) {
-            return {
-                $ref: resolveRef(refUrl),
-            };
+        const ref = resolveExternalRef(property);
+        if (ref) {
+            return ref;
         }
         const parameter = params.get(property);
         if (parameter) {
@@ -611,33 +684,66 @@ export async function getOpenAPIForService(context, options) {
             currentConsumes.add(consume);
         }
         if (methodParams.body && !isVoidType(methodParams.body.type)) {
-            const isBinary = isBinaryPayload(methodParams.body.type, consumes);
-            const schemaContext = {
-                visibility,
-                ignoreMetadataAnnotations: methodParams.body.isExplicit && methodParams.body.containsMetadataAnnotations,
-            };
-            const schema = isBinary
-                ? { type: "string", format: "binary" }
-                : getSchemaOrRef(methodParams.body.type, schemaContext);
-            if (currentConsumes.has("multipart/form-data")) {
-                const bodyModelType = methodParams.body.type;
-                // Assert, this should never happen. Rest library guard against that.
-                compilerAssert(bodyModelType.kind === "Model", "Body should always be a Model.");
-                if (bodyModelType) {
-                    for (const param of bodyModelType.properties.values()) {
-                        emitParameter(param, "formData", schemaContext, getJsonName(param));
-                    }
+            emitBodyParameters(methodParams.body, visibility);
+        }
+    }
+    function emitBodyParameters(body, visibility) {
+        switch (body.bodyKind) {
+            case "single":
+                emitSingleBodyParameters(body, visibility);
+                break;
+            case "multipart":
+                emitMultipartBodyParameters(body, visibility);
+                break;
+        }
+    }
+    function emitSingleBodyParameters(body, visibility) {
+        const isBinary = isBinaryPayload(body.type, body.contentTypes);
+        const schemaContext = {
+            visibility,
+            ignoreMetadataAnnotations: body.isExplicit && body.containsMetadataAnnotations,
+        };
+        const schema = isBinary
+            ? { type: "string", format: "binary" }
+            : getSchemaOrRef(body.type, schemaContext);
+        if (currentConsumes.has("multipart/form-data")) {
+            const bodyModelType = body.type;
+            // Assert, this should never happen. Rest library guard against that.
+            compilerAssert(bodyModelType.kind === "Model", "Body should always be a Model.");
+            if (bodyModelType) {
+                for (const param of bodyModelType.properties.values()) {
+                    emitParameter(param, "formData", schemaContext, getJsonName(param));
                 }
             }
-            else if (methodParams.body.parameter) {
-                emitParameter(methodParams.body.parameter, "body", { visibility, ignoreMetadataAnnotations: false }, getJsonName(methodParams.body.parameter), schema);
-            }
-            else {
+        }
+        else if (body.property) {
+            emitParameter(body.property, "body", { visibility, ignoreMetadataAnnotations: false }, getJsonName(body.property), schema);
+        }
+        else {
+            currentEndpoint.parameters.push({
+                name: "body",
+                in: "body",
+                schema,
+                required: true,
+            });
+        }
+    }
+    function emitMultipartBodyParameters(body, visibility) {
+        for (const [index, part] of body.parts.entries()) {
+            const partName = part.name ?? `part${index}`;
+            let schema = getFormDataSchema(part.body.type, { visibility, ignoreMetadataAnnotations: false }, partName);
+            if (schema) {
+                if (part.multi) {
+                    schema = {
+                        type: "array",
+                        items: schema.type === "file" ? { type: "string", format: "binary" } : schema,
+                    };
+                }
                 currentEndpoint.parameters.push({
-                    name: "body",
-                    in: "body",
-                    schema,
-                    required: true,
+                    name: partName,
+                    in: "formData",
+                    required: !part.optional,
+                    ...schema,
                 });
             }
         }
@@ -848,13 +954,13 @@ export async function getOpenAPIForService(context, options) {
             }
             return false;
         }
-        function isVersionEnum(program, enumObj) {
-            const versions = getVersionsForEnum(program, enumObj);
-            if (versions !== undefined && versions.length > 0) {
-                return true;
-            }
-            return false;
+    }
+    function isVersionEnum(program, enumObj) {
+        const [_, map] = getVersionsForEnum(program, enumObj);
+        if (map !== undefined && map.getVersions()[0].enumMember.enum === enumObj) {
+            return true;
         }
+        return false;
     }
     function emitTags() {
         for (const tag of tags) {
@@ -903,6 +1009,29 @@ export async function getOpenAPIForService(context, options) {
         });
         return {};
     }
+    /**
+     * Version enum is special so we we just render the current version with modelAsString: true
+     */
+    function getSchemaForVersionEnum(e, currentVersion) {
+        const member = [...e.members.values()].find((x) => (x.value ?? x.name) === currentVersion);
+        compilerAssert(member, `Version enum ${e.name} does not have a member for ${currentVersion}.`, e);
+        return {
+            type: "string",
+            description: getDoc(program, e),
+            enum: [member.value ?? member.name],
+            "x-ms-enum": {
+                name: e.name,
+                modelAsString: true,
+                values: [
+                    {
+                        name: member.name,
+                        value: member.value ?? member.name,
+                        description: getDoc(program, member),
+                    },
+                ],
+            },
+        };
+    }
     function getSchemaForEnum(e) {
         const values = [];
         if (e.members.size === 0) {
@@ -919,6 +1048,10 @@ export async function getOpenAPIForService(context, options) {
                 values.push(option.value ?? option.name);
             }
         }
+        // If we are rendering a specific version and trying to render the version enum we should treat it specially to only include the current version.
+        if (isVersionEnum(program, e) && context.version) {
+            return getSchemaForVersionEnum(e, context.version);
+        }
         const schema = { type, description: getDoc(program, e) };
         if (values.length > 0) {
             schema.enum = values;
@@ -1115,6 +1248,7 @@ export async function getOpenAPIForService(context, options) {
                 modelSchema.required = [propertyName];
             }
         }
+        applySummary(model, modelSchema);
         applyExternalDocs(model, modelSchema);
         for (const prop of model.properties.values()) {
             if (!metadataInfo.isPayloadProperty(prop, schemaContext.visibility, schemaContext.ignoreMetadataAnnotations)) {
@@ -1150,6 +1284,7 @@ export async function getOpenAPIForService(context, options) {
             if (description) {
                 property.description = description;
             }
+            applySummary(prop, property);
             if (prop.defaultValue && !("$ref" in property)) {
                 property.default = getDefaultValue(prop.defaultValue);
             }
@@ -1215,10 +1350,10 @@ export async function getOpenAPIForService(context, options) {
     }
     function resolveProperty(prop, context) {
         let propSchema;
-        if (prop.type.kind === "Enum" && prop.default) {
+        if (prop.type.kind === "Enum" && prop.defaultValue) {
             propSchema = getSchemaForEnum(prop.type);
         }
-        else if (prop.type.kind === "Union" && prop.default) {
+        else if (prop.type.kind === "Union" && prop.defaultValue) {
             const [asEnum, _] = getUnionAsEnum(prop.type);
             if (asEnum) {
                 propSchema = getSchemaForUnionEnum(prop.type, asEnum);
@@ -1275,6 +1410,10 @@ export async function getOpenAPIForService(context, options) {
         if (docStr) {
             newTarget.description = docStr;
         }
+        const title = getSummary(program, typespecType);
+        if (title) {
+            target.title = title;
+        }
         const formatStr = getFormat(program, typespecType);
         if (isString && formatStr) {
             const allowedStringFormats = [
@@ -1394,6 +1533,12 @@ export async function getOpenAPIForService(context, options) {
                 return encodeAsFormat ?? encoding;
         }
     }
+    function applySummary(typespecType, target) {
+        const summary = getSummary(program, typespecType);
+        if (summary) {
+            target.title = summary;
+        }
+    }
     function applyExternalDocs(typespecType, target) {
         const externalDocs = getExternalDocs(program, typespecType);
         if (externalDocs) {
@@ -1404,7 +1549,7 @@ export async function getOpenAPIForService(context, options) {
         if (type.node && type.node.parent && type.node.parent.kind === SyntaxKind.ModelStatement) {
             schema["x-ms-enum"] = {
                 name: type.node.parent.id.sv,
-                modelAsString: true,
+                modelAsString: false,
             };
         }
         else if (type.kind === "String") {
@@ -1415,7 +1560,7 @@ export async function getOpenAPIForService(context, options) {
         else if (type.kind === "Enum") {
             schema["x-ms-enum"] = {
                 name: type.name,
-                modelAsString: isFixed(program, type) ? false : true,
+                modelAsString: false,
             };
             const values = [];
             let foundCustom = false;
@@ -1437,12 +1582,14 @@ export async function getOpenAPIForService(context, options) {
         return schema;
     }
     function getSchemaForStringTemplate(stringTemplate) {
-        const [value, diagnostics] = stringTemplateToString(stringTemplate);
-        if (diagnostics.length > 0) {
-            program.reportDiagnostics(diagnostics.map((x) => ({ ...x, severity: "warning" })));
+        if (stringTemplate.stringValue === undefined) {
+            program.reportDiagnostics(explainStringTemplateNotSerializable(stringTemplate).map((x) => ({
+                ...x,
+                severity: "warning",
+            })));
             return { type: "string" };
         }
-        return { type: "string", enum: [value] };
+        return { type: "string", enum: [stringTemplate.stringValue] };
     }
     function getSchemaForLiterals(typespecType) {
         switch (typespecType.kind) {
@@ -1654,7 +1801,7 @@ class ErrorTypeFoundError extends Error {
 export function sortOpenAPIDocument(doc) {
     // Doing this to make sure the classes with toJSON are resolved.
     const unsorted = JSON.parse(JSON.stringify(doc));
-    const sorted = sortWithJsonSchema(unsorted, AutorestOpenAPISchema, "#/$defs/AutorestOpenAPISchema");
+    const sorted = sortWithJsonSchema(unsorted, AutorestOpenAPISchema);
     return sorted;
 }
 async function loadExamples(host, options, version) {