@typespec/openapi3 0.59.0-dev.0 → 0.59.0-dev.10

package/dist/src/openapi.js

@@ -1,13 +1,16 @@
-import { compilerAssert, createDiagnosticCollector, emitFile, getAllTags, getAnyExtensionFromPath, getDoc, getEncode, getFormat, getKnownValues, getMaxItems, getMaxLength, getMaxValue, getMaxValueExclusive, getMinItems, getMinLength, getMinValue, getMinValueExclusive, getNamespaceFullName, getOpExamples, getPattern, getService, getSummary, ignoreDiagnostics, interpolatePath, isDeprecated, isGlobalNamespace, isNeverType, isSecret, isVoidType, listServices, navigateTypesInNamespace, projectProgram, resolvePath, serializeValueAsJson, } from "@typespec/compiler";
+import { compilerAssert, createDiagnosticCollector, emitFile, getAllTags, getAnyExtensionFromPath, getDoc, getFormat, getKnownValues, getMaxItems, getMaxLength, getMaxValue, getMaxValueExclusive, getMinItems, getMinLength, getMinValue, getMinValueExclusive, getNamespaceFullName, getPattern, getService, getSummary, ignoreDiagnostics, interpolatePath, isDeprecated, isGlobalNamespace, isNeverType, isSecret, isVoidType, listServices, navigateTypesInNamespace, projectProgram, resolvePath, } from "@typespec/compiler";
 import { createAssetEmitter } from "@typespec/compiler/emitter-framework";
 import { createMetadataInfo, getHttpService, getServers, getStatusCodeDescription, isContentTypeHeader, isOrExtendsHttpFile, isOverloadSameEndpoint, reportIfNoRoutes, resolveAuthentication, resolveRequestVisibility, Visibility, } from "@typespec/http";
-import { getExtensions, getExternalDocs, getOpenAPITypeName, getParameterKey, isDefaultResponse, isReadonlyProperty, resolveInfo, resolveOperationId, shouldInline, } from "@typespec/openapi";
+import { getExtensions, getExternalDocs, getOpenAPITypeName, getParameterKey, isReadonlyProperty, resolveInfo, resolveOperationId, shouldInline, } from "@typespec/openapi";
 import { buildVersionProjections } from "@typespec/versioning";
 import { stringify } from "yaml";
 import { getRef } from "./decorators.js";
+import { applyEncoding } from "./encoding.js";
+import { getExampleOrExamples, resolveOperationExamples } from "./examples.js";
 import { createDiagnostic } from "./lib.js";
 import { getDefaultValue, isBytesKeptRaw, OpenAPI3SchemaEmitter } from "./schema-emitter.js";
-import { deepEquals, isDefined } from "./util.js";
+import { getOpenAPI3StatusCodes } from "./status-codes.js";
+import { deepEquals, isSharedHttpOperation } from "./util.js";
 import { resolveVisibilityUsage } from "./visibility-usage.js";
 const defaultFileType = "yaml";
 const defaultOptions = {
@@ -76,10 +79,10 @@ function createOAPIEmitter(context, options) {
     let root;
     let diagnostics;
     let currentService;
+    let serviceAuth;
     // Get the service namespace string for use in name shortening
     let serviceNamespaceName;
     let currentPath;
-    let currentEndpoint;
     let metadataInfo;
     let visibilityUsage;
     // Map model properties that represent shared parameters to their parameter
@@ -175,6 +178,7 @@ function createOAPIEmitter(context, options) {
         if (servers) {
             root.servers = resolveServers(servers);
         }
+        attachExtensions(program, service.type, root);
         serviceNamespaceName = getNamespaceFullName(service.type);
         currentPath = root.paths;
         params = new Map();
@@ -315,15 +319,7 @@ function createOAPIEmitter(context, options) {
     /**
      * Validates that common responses are consistent and returns the minimal set that describes the differences.
      */
-    function validateCommonResponses(statusCode, ops) {
-        const statusCodeResponses = [];
-        for (const op of ops) {
-            for (const response of op.responses) {
-                if (getOpenAPI3StatusCodes(response.statusCodes, response.type).includes(statusCode)) {
-                    statusCodeResponses.push(response);
-                }
-            }
-        }
+    function deduplicateCommonResponses(statusCodeResponses) {
         const ref = statusCodeResponses[0];
         const sameTypeKind = statusCodeResponses.every((r) => r.type.kind === ref.type.kind);
         const sameTypeValue = statusCodeResponses.every((r) => r.type === ref.type);
@@ -335,156 +331,61 @@ function createOAPIEmitter(context, options) {
             return statusCodeResponses;
         }
     }
-    /**
-     * Validates that common bodies are consistent and returns the minimal set that describes the differences.
-     */
-    function validateCommonBodies(ops) {
-        const allBodies = ops.map((op) => op.parameters.body);
-        return [...new Set(allBodies)];
-    }
     /**
      * Validates that common parameters are consistent and returns the minimal set that describes the differences.
      */
-    function validateCommonParameters(ops, name, totalOps) {
+    function resolveSharedRouteParameters(ops) {
         const finalParams = [];
-        const commonParams = [];
+        const parameters = new Map();
         for (const op of ops) {
-            const param = op.parameters.parameters.find((p) => p.name === name);
-            if (param) {
-                commonParams.push(param);
+            for (const parameter of op.parameters.parameters) {
+                const existing = parameters.get(parameter.name);
+                if (existing) {
+                    existing.push(parameter);
+                }
+                else {
+                    parameters.set(parameter.name, [parameter]);
+                }
             }
         }
-        const reference = commonParams[0];
-        if (!reference) {
+        if (parameters.size === 0) {
             return [];
         }
-        const inAllOps = ops.length === totalOps;
-        const sameLocations = commonParams.every((p) => p.type === reference.type);
-        const sameOptionality = commonParams.every((p) => p.param.optional === reference.param.optional);
-        const sameTypeKind = commonParams.every((p) => p.param.type.kind === reference.param.type.kind);
-        const sameTypeValue = commonParams.every((p) => p.param.type === reference.param.type);
-        if (inAllOps && sameLocations && sameOptionality && sameTypeKind && sameTypeValue) {
-            // param is consistent and in all shared operations. Only need one copy.
-            finalParams.push(reference);
-        }
-        else if (!inAllOps && sameLocations && sameOptionality && sameTypeKind && sameTypeValue) {
-            // param is consistent when used, but does not appear in all shared operations. Only need one copy, but it must be optional.
-            reference.param.optional = true;
-            finalParams.push(reference);
-        }
-        else if (inAllOps && !(sameLocations && sameOptionality && sameTypeKind)) {
-            // param is in all shared operations, but is not consistent. Need multiple copies, which must be optional.
-            // exception allowed when the params only differ by their value (e.g. string enum values)
-            commonParams.forEach((p) => {
-                p.param.optional = true;
-            });
-            finalParams.push(...commonParams);
-        }
-        else {
-            finalParams.push(...commonParams);
-        }
-        return finalParams;
-    }
-    function getOpenAPI3StatusCodes(statusCodes, response) {
-        if (isDefaultResponse(program, response) || statusCodes === "*") {
-            return ["default"];
-        }
-        else if (typeof statusCodes === "number") {
-            return [String(statusCodes)];
-        }
-        else {
-            return rangeToOpenAPI(statusCodes, response);
-        }
-    }
-    function rangeToOpenAPI(range, diagnosticTarget) {
-        const reportInvalid = () => diagnostics.add(createDiagnostic({
-            code: "unsupported-status-code-range",
-            format: { start: String(range.start), end: String(range.end) },
-            target: diagnosticTarget,
-        }));
-        const codes = [];
-        let start = range.start;
-        let end = range.end;
-        if (range.start < 100) {
-            reportInvalid();
-            start = 100;
-            codes.push("default");
-        }
-        else if (range.end > 599) {
-            reportInvalid();
-            codes.push("default");
-            end = 599;
-        }
-        const groups = [1, 2, 3, 4, 5];
-        for (const group of groups) {
-            if (start > end) {
-                break;
+        for (const sharedParams of parameters.values()) {
+            const reference = sharedParams[0];
+            const inAllOps = ops.length === sharedParams.length;
+            const sameLocations = sharedParams.every((p) => p.type === reference.type);
+            const sameOptionality = sharedParams.every((p) => p.param.optional === reference.param.optional);
+            const sameTypeKind = sharedParams.every((p) => p.param.type.kind === reference.param.type.kind);
+            const sameTypeValue = sharedParams.every((p) => p.param.type === reference.param.type);
+            if (inAllOps && sameLocations && sameOptionality && sameTypeKind && sameTypeValue) {
+                // param is consistent and in all shared operations. Only need one copy.
+                finalParams.push(reference);
             }
-            const groupStart = group * 100;
-            const groupEnd = groupStart + 99;
-            if (start >= groupStart && start <= groupEnd) {
-                codes.push(`${group}XX`);
-                if (start !== groupStart || end < groupEnd) {
-                    reportInvalid();
-                }
-                start = groupStart + 100;
+            else if (!inAllOps && sameLocations && sameOptionality && sameTypeKind && sameTypeValue) {
+                // param is consistent when used, but does not appear in all shared operations. Only need one copy, but it must be optional.
+                reference.param.optional = true;
+                finalParams.push(reference);
             }
-        }
-        return codes;
-    }
-    function buildSharedOperations(operations) {
-        const results = [];
-        const paramMap = new Map();
-        const responseMap = new Map();
-        for (const op of operations) {
-            // determine which parameters are shared by shared route operations
-            for (const param of op.parameters.parameters) {
-                if (paramMap.has(param.name)) {
-                    paramMap.get(param.name).push(op);
-                }
-                else {
-                    paramMap.set(param.name, [op]);
-                }
+            else if (inAllOps && !(sameLocations && sameOptionality && sameTypeKind)) {
+                // param is in all shared operations, but is not consistent. Need multiple copies, which must be optional.
+                // exception allowed when the params only differ by their value (e.g. string enum values)
+                sharedParams.forEach((p) => {
+                    p.param.optional = true;
+                });
+                finalParams.push(...sharedParams);
             }
-            // determine which responses are shared by shared route operations
-            for (const response of op.responses) {
-                const statusCodes = getOpenAPI3StatusCodes(response.statusCodes, op.operation);
-                for (const statusCode of statusCodes) {
-                    if (responseMap.has(statusCode)) {
-                        responseMap.get(statusCode).push(op);
-                    }
-                    else {
-                        responseMap.set(statusCode, [op]);
-                    }
-                }
+            else {
+                finalParams.push(...sharedParams);
             }
         }
-        const totalOps = operations.length;
-        const shared = {
+        return finalParams;
+    }
+    function buildSharedOperation(operations) {
+        return {
             kind: "shared",
-            operationId: operations.map((op) => resolveOperationId(program, op.operation)).join("_"),
-            description: joinOps(operations, getDoc, " "),
-            summary: joinOps(operations, getSummary, " "),
-            path: operations[0].path,
-            verb: operations[0].verb,
-            operations: operations.map((op) => op.operation),
-            parameters: {
-                parameters: [],
-            },
-            bodies: undefined,
-            authentication: operations[0].authentication,
-            responses: new Map(),
+            operations: operations,
         };
-        for (const [paramName, ops] of paramMap) {
-            const commonParams = validateCommonParameters(ops, paramName, totalOps);
-            shared.parameters.parameters.push(...commonParams);
-        }
-        shared.bodies = validateCommonBodies(operations);
-        for (const [statusCode, ops] of responseMap) {
-            shared.responses.set(statusCode, validateCommonResponses(statusCode, ops));
-        }
-        results.push(shared);
-        return results;
     }
     /**
      * Groups HttpOperations together if they share the same route.
@@ -506,10 +407,7 @@ function createOAPIEmitter(context, options) {
                 result.push(ops[0]);
             }
             else {
-                const sharedOps = buildSharedOperations(ops);
-                for (const op of sharedOps) {
-                    result.push(op);
-                }
+                result.push(buildSharedOperation(ops));
             }
         }
         return result;
@@ -517,17 +415,15 @@ function createOAPIEmitter(context, options) {
     async function getOpenApiFromVersion(service, version) {
         try {
             const httpService = ignoreDiagnostics(getHttpService(program, service.type));
-            const auth = resolveAuthentication(httpService);
+            const auth = (serviceAuth = resolveAuthentication(httpService));
             initializeEmitter(service, auth.schemes, auth.defaultAuth, version);
             reportIfNoRoutes(program, httpService.operations);
             for (const op of resolveOperations(httpService.operations)) {
-                if (op.kind === "shared") {
-                    const opAuth = auth.operationsAuth.get(op.operations[0]);
-                    emitSharedOperation(op, opAuth);
-                }
-                else {
-                    const opAuth = auth.operationsAuth.get(op.operation);
-                    emitOperation(op, opAuth);
+                const result = getOperationOrSharedOperation(op);
+                if (result) {
+                    const { operation, path, verb } = result;
+                    currentPath[path] ??= {};
+                    currentPath[path][verb] = operation;
                 }
             }
             emitParameters();
@@ -565,26 +461,46 @@ function createOAPIEmitter(context, options) {
             return undefined;
         }
     }
-    function emitSharedOperation(shared, authReference) {
-        const { path: fullPath, verb: verb, operations: ops } = shared;
-        if (!root.paths[fullPath]) {
-            root.paths[fullPath] = {};
+    function computeSharedOperationId(shared) {
+        return shared.operations.map((op) => resolveOperationId(program, op.operation)).join("_");
+    }
+    function getOperationOrSharedOperation(operation) {
+        if (isSharedHttpOperation(operation)) {
+            return getSharedOperation(operation);
         }
-        currentPath = root.paths[fullPath];
-        if (!currentPath[verb]) {
-            currentPath[verb] = {};
+        else {
+            return getOperation(operation);
         }
-        currentEndpoint = currentPath[verb];
-        for (const op of ops) {
-            const opTags = getAllTags(program, op);
+    }
+    function getSharedOperation(shared) {
+        const operations = shared.operations;
+        const verb = operations[0].verb;
+        const path = operations[0].path;
+        const examples = resolveOperationExamples(program, shared);
+        const oai3Operation = {
+            operationId: computeSharedOperationId(shared),
+            parameters: [],
+            description: joinOps(operations, getDoc, " "),
+            summary: joinOps(operations, getSummary, " "),
+            responses: getSharedResponses(shared, examples),
+        };
+        for (const op of operations) {
+            applyExternalDocs(op.operation, oai3Operation);
+            attachExtensions(program, op.operation, oai3Operation);
+            if (isDeprecated(program, op.operation)) {
+                oai3Operation.deprecated = true;
+            }
+        }
+        for (const op of operations) {
+            const opTags = getAllTags(program, op.operation);
             if (opTags) {
-                const currentTags = currentEndpoint.tags;
+                const currentTags = oai3Operation.tags;
                 if (currentTags) {
                     // combine tags but eliminate duplicates
-                    currentEndpoint.tags = [...new Set([...currentTags, ...opTags])];
+                    oai3Operation.tags = [...new Set([...currentTags, ...opTags])];
                 }
                 else {
-                    currentEndpoint.tags = opTags;
+                    oai3Operation.tags = opTags;
                 }
                 for (const tag of opTags) {
                     // Add to root tags if not already there
@@ -592,105 +508,98 @@ function createOAPIEmitter(context, options) {
                 }
             }
         }
-        // Set up basic endpoint fields
-        currentEndpoint.operationId = shared.operationId;
-        for (const op of ops) {
-            applyExternalDocs(op, currentEndpoint);
-        }
-        currentEndpoint.summary = shared.summary;
-        currentEndpoint.description = shared.description;
-        currentEndpoint.parameters = [];
-        currentEndpoint.responses = {};
         // Error out if shared routes do not have consistent `@parameterVisibility`. We can
         // lift this restriction in the future if a use case develops.
-        const visibilities = shared.operations.map((op) => {
-            return resolveRequestVisibility(program, op, verb);
-        });
+        const visibilities = operations.map((op) => resolveRequestVisibility(program, op.operation, verb));
         if (visibilities.some((v) => v !== visibilities[0])) {
             diagnostics.add(createDiagnostic({
                 code: "inconsistent-shared-route-request-visibility",
-                target: ops[0],
+                target: operations[0].operation,
             }));
         }
-        const visibility = resolveRequestVisibility(program, shared.operations[0], verb);
-        emitEndpointParameters(shared.parameters.parameters, visibility);
-        if (shared.bodies) {
-            if (shared.bodies.length === 1) {
-                emitRequestBody(shared, shared.bodies[0], visibility);
-            }
-            else if (shared.bodies.length > 1) {
-                emitMergedRequestBody(shared, shared.bodies, visibility);
-            }
-        }
-        emitSharedResponses(shared, shared.responses);
-        for (const op of ops) {
-            if (isDeprecated(program, op)) {
-                currentEndpoint.deprecated = true;
-            }
-            attachExtensions(program, op, currentEndpoint);
+        const visibility = visibilities[0];
+        oai3Operation.parameters = getEndpointParameters(resolveSharedRouteParameters(operations), visibility);
+        const bodies = [
+            ...new Set(operations.map((op) => op.parameters.body).filter((x) => x !== undefined)),
+        ];
+        if (bodies) {
+            oai3Operation.requestBody = getRequestBody(bodies, visibility, examples);
         }
+        const authReference = serviceAuth.operationsAuth.get(shared.operations[0].operation);
         if (authReference) {
-            emitEndpointSecurity(authReference);
+            oai3Operation.security = getEndpointSecurity(authReference);
         }
+        return { operation: oai3Operation, verb, path };
     }
-    function emitOperation(operation, authReference) {
+    function getOperation(operation) {
         const { path: fullPath, operation: op, verb, parameters } = operation;
         // If path contains a query string, issue msg and don't emit this endpoint
         if (fullPath.indexOf("?") > 0) {
             diagnostics.add(createDiagnostic({ code: "path-query", target: op }));
-            return;
-        }
-        if (!root.paths[fullPath]) {
-            root.paths[fullPath] = {};
-        }
-        currentPath = root.paths[fullPath];
-        if (!currentPath[verb]) {
-            currentPath[verb] = {};
+            return undefined;
         }
-        currentEndpoint = currentPath[verb];
+        const visibility = resolveRequestVisibility(program, operation.operation, verb);
+        const examples = resolveOperationExamples(program, operation);
+        const oai3Operation = {
+            operationId: resolveOperationId(program, operation.operation),
+            summary: getSummary(program, operation.operation),
+            description: getDoc(program, operation.operation),
+            parameters: getEndpointParameters(parameters.parameters, visibility),
+            responses: getResponses(operation, operation.responses, examples),
+        };
         const currentTags = getAllTags(program, op);
         if (currentTags) {
-            currentEndpoint.tags = currentTags;
+            oai3Operation.tags = currentTags;
             for (const tag of currentTags) {
                 // Add to root tags if not already there
                 tags.add(tag);
             }
         }
-        currentEndpoint.operationId = resolveOperationId(program, operation.operation);
-        applyExternalDocs(op, currentEndpoint);
+        applyExternalDocs(op, oai3Operation);
         // Set up basic endpoint fields
-        currentEndpoint.summary = getSummary(program, operation.operation);
-        currentEndpoint.description = getDoc(program, operation.operation);
-        currentEndpoint.parameters = [];
-        currentEndpoint.responses = {};
-        const visibility = resolveRequestVisibility(program, operation.operation, verb);
-        emitEndpointParameters(parameters.parameters, visibility);
-        emitRequestBody(operation, parameters.body, visibility);
-        emitResponses(operation, operation.responses);
+        if (parameters.body) {
+            oai3Operation.requestBody = getRequestBody(parameters.body && [parameters.body], visibility, examples);
+        }
+        const authReference = serviceAuth.operationsAuth.get(operation.operation);
         if (authReference) {
-            emitEndpointSecurity(authReference);
+            oai3Operation.security = getEndpointSecurity(authReference);
         }
         if (isDeprecated(program, op)) {
-            currentEndpoint.deprecated = true;
+            oai3Operation.deprecated = true;
         }
-        attachExtensions(program, op, currentEndpoint);
+        attachExtensions(program, op, oai3Operation);
+        return { operation: oai3Operation, path: fullPath, verb };
     }
-    function emitSharedResponses(operation, responses) {
-        for (const [statusCode, statusCodeResponses] of responses) {
-            if (statusCodeResponses.length === 1) {
-                emitResponseObject(operation, statusCode, statusCodeResponses[0]);
-            }
-            else {
-                emitMergedResponseObject(operation, statusCode, statusCodeResponses);
+    function getSharedResponses(operation, examples) {
+        const responseMap = new Map();
+        for (const op of operation.operations) {
+            for (const response of op.responses) {
+                const statusCodes = diagnostics.pipe(getOpenAPI3StatusCodes(program, response.statusCodes, op.operation));
+                for (const statusCode of statusCodes) {
+                    if (responseMap.has(statusCode)) {
+                        responseMap.get(statusCode).push(response);
+                    }
+                    else {
+                        responseMap.set(statusCode, [response]);
+                    }
+                }
             }
         }
+        const result = {};
+        for (const [statusCode, statusCodeResponses] of responseMap) {
+            const dedupeResponses = deduplicateCommonResponses(statusCodeResponses);
+            result[statusCode] = getResponseForStatusCode(operation, statusCode, dedupeResponses, examples);
+        }
+        return result;
     }
-    function emitResponses(operation, responses) {
+    function getResponses(operation, responses, examples) {
+        const result = {};
         for (const response of responses) {
-            for (const statusCode of getOpenAPI3StatusCodes(response.statusCodes, response.type)) {
-                emitResponseObject(operation, statusCode, response);
+            for (const statusCode of diagnostics.pipe(getOpenAPI3StatusCodes(program, response.statusCodes, response.type))) {
+                result[statusCode] = getResponseForStatusCode(operation, statusCode, [response], examples);
             }
         }
+        return result;
     }
     function isBinaryPayload(body, contentType) {
         return (body.kind === "Scalar" &&
@@ -698,33 +607,28 @@ function createOAPIEmitter(context, options) {
             contentType !== "application/json" &&
             contentType !== "text/plain");
     }
-    function emitMergedResponseObject(operation, statusCode, responses) {
+    function getResponseForStatusCode(operation, statusCode, responses, examples) {
         const openApiResponse = {
-            description: undefined,
-            content: {},
+            description: "",
         };
         const schemaMap = new Map();
         for (const response of responses) {
+            const refUrl = getRef(program, response.type);
+            if (refUrl) {
+                return { $ref: refUrl };
+            }
             if (response.description && response.description !== openApiResponse.description) {
                 openApiResponse.description = openApiResponse.description
                     ? `${openApiResponse.description} ${response.description}`
                     : response.description;
             }
             emitResponseHeaders(openApiResponse, response.responses, response.type);
-            emitResponseContent(operation, openApiResponse, response.responses, schemaMap);
+            emitResponseContent(operation, openApiResponse, response.responses, statusCode, examples, schemaMap);
             if (!openApiResponse.description) {
                 openApiResponse.description = getResponseDescriptionForStatusCode(statusCode);
             }
-            currentEndpoint.responses[statusCode] = openApiResponse;
         }
-    }
-    function emitResponseObject(operation, statusCode, response) {
-        const openApiResponse = currentEndpoint.responses[statusCode] ?? {
-            description: response.description ?? getResponseDescriptionForStatusCode(statusCode),
-        };
-        emitResponseHeaders(openApiResponse, response.responses, response.type);
-        emitResponseContent(operation, openApiResponse, response.responses);
-        currentEndpoint.responses[statusCode] = openApiResponse;
+        return openApiResponse;
     }
     function emitResponseHeaders(obj, responses, target) {
         for (const data of responses) {
@@ -750,7 +654,7 @@ function createOAPIEmitter(context, options) {
             }
         }
     }
-    function emitResponseContent(operation, obj, responses, schemaMap = undefined) {
+    function emitResponseContent(operation, obj, responses, statusCode, examples, schemaMap = undefined) {
         schemaMap ??= new Map();
         for (const data of responses) {
             if (data.body === undefined) {
@@ -758,7 +662,7 @@ function createOAPIEmitter(context, options) {
             }
             obj.content ??= {};
             for (const contentType of data.body.contentTypes) {
-                const contents = getBodyContentEntry(operation, "response", data.body, Visibility.Read, contentType);
+                const contents = getBodyContentEntry(data.body, Visibility.Read, contentType, examples.responses[statusCode]?.[contentType]);
                 if (schemaMap.has(contentType)) {
                     schemaMap.get(contentType).push(contents);
                 }
@@ -836,70 +740,22 @@ function createOAPIEmitter(context, options) {
             },
         });
     }
-    function isSharedHttpOperation(operation) {
-        return operation.kind === "shared";
-    }
-    function findOperationExamples(operation) {
-        if (isSharedHttpOperation(operation)) {
-            return operation.operations.flatMap((op) => getOpExamples(program, op).map((x) => [op, x]));
-        }
-        else {
-            return getOpExamples(program, operation.operation).map((x) => [operation.operation, x]);
-        }
-    }
-    function getExamplesForBodyContentEntry(operation, target) {
-        const examples = findOperationExamples(operation);
-        if (examples.length === 0) {
-            return {};
-        }
-        const flattenedExamples = examples
-            .map(([op, example]) => {
-            const value = target === "request" ? example.parameters : example.returnType;
-            const type = target === "request" ? op.parameters : op.returnType;
-            return value
-                ? [{ value, title: example.title, description: example.description }, type]
-                : undefined;
-        })
-            .filter(isDefined);
-        return getExampleOrExamples(flattenedExamples);
-    }
-    function getExampleOrExamples(examples) {
-        if (examples.length === 0) {
-            return {};
-        }
-        if (examples.length === 1 &&
-            examples[0][0].title === undefined &&
-            examples[0][0].description === undefined) {
-            const [example, type] = examples[0];
-            return { example: serializeValueAsJson(program, example.value, type) };
-        }
-        else {
-            const exampleObj = {};
-            for (const [index, [example, type]] of examples.entries()) {
-                exampleObj[example.title ?? `example${index}`] = {
-                    summary: example.title,
-                    description: example.description,
-                    value: serializeValueAsJson(program, example.value, type),
-                };
-            }
-            return { examples: exampleObj };
-        }
-    }
-    function getBodyContentEntry(operation, target, body, visibility, contentType) {
+    function getBodyContentEntry(body, visibility, contentType, examples) {
         const isBinary = isBinaryPayload(body.type, contentType);
         if (isBinary) {
             return { schema: { type: "string", format: "binary" } };
         }
+        const oai3Examples = examples && getExampleOrExamples(program, examples);
         switch (body.bodyKind) {
             case "single":
                 return {
                     schema: getSchemaForSingleBody(body.type, visibility, body.isExplicit && body.containsMetadataAnnotations, contentType.startsWith("multipart/") ? contentType : undefined),
-                    ...getExamplesForBodyContentEntry(operation, target),
+                    ...oai3Examples,
                 };
             case "multipart":
                 return {
                     ...getBodyContentForMultipartBody(body, visibility, contentType),
-                    ...getExamplesForBodyContentEntry(operation, target),
+                    ...oai3Examples,
                 };
         }
     }
@@ -991,56 +847,57 @@ function createOAPIEmitter(context, options) {
         }
         return false;
     }
-    function getParamPlaceholder(property) {
-        let spreadParam = false;
-        if (property.sourceProperty) {
-            // chase our sources all the way back to the first place this property
-            // was defined.
-            spreadParam = true;
-            property = property.sourceProperty;
-            while (property.sourceProperty) {
-                property = property.sourceProperty;
-            }
-        }
-        const refUrl = getRef(program, property);
-        if (refUrl) {
-            return {
-                $ref: refUrl,
+    function getParameter(parameter, visibility) {
+        const param = {
+            name: parameter.name,
+            in: parameter.type,
+            ...getOpenAPIParameterBase(parameter.param, visibility),
+        };
+        const format = mapParameterFormat(parameter);
+        if (format === undefined) {
+            param.schema = {
+                type: "string",
             };
         }
-        if (params.has(property)) {
-            return params.get(property);
-        }
-        const placeholder = {};
-        // only parameters inherited by spreading from non-inlined type are shared in #/components/parameters
-        if (spreadParam && property.model && !shouldInline(program, property.model)) {
-            params.set(property, placeholder);
-            paramModels.add(property.model);
+        else {
+            Object.assign(param, format);
         }
-        return placeholder;
+        return param;
     }
-    function emitEndpointParameters(parameters, visibility) {
+    function getEndpointParameters(parameters, visibility) {
+        const result = [];
         for (const httpOpParam of parameters) {
             if (params.has(httpOpParam.param)) {
-                currentEndpoint.parameters.push(params.get(httpOpParam.param));
+                result.push(params.get(httpOpParam.param));
                 continue;
             }
+            // eslint-disable-next-line deprecation/deprecation
             if (httpOpParam.type === "header" && isContentTypeHeader(program, httpOpParam.param)) {
                 continue;
             }
-            emitParameter(httpOpParam, visibility);
+            const param = getParameterOrRef(httpOpParam, visibility);
+            if (param) {
+                const existing = result.find((x) => !("$ref" in param) && !("$ref" in x) && x.name === param.name && x.in === param.in);
+                if (existing && !("$ref" in param) && !("$ref" in existing)) {
+                    mergeOpenApiParameters(existing, param);
+                }
+                else {
+                    result.push(param);
+                }
+            }
         }
+        return result;
     }
-    function emitMergedRequestBody(operation, bodies, visibility) {
-        if (bodies === undefined) {
-            return;
+    function getRequestBody(bodies, visibility, examples) {
+        if (bodies === undefined || bodies.every((x) => isVoidType(x.type))) {
+            return undefined;
         }
         const requestBody = {
-            description: undefined,
+            required: bodies.every((body) => (body.property ? !body.property.optional : true)),
             content: {},
         };
         const schemaMap = new Map();
-        for (const body of bodies) {
+        for (const body of bodies.filter((x) => !isVoidType(x.type))) {
             const desc = body.property ? getDoc(program, body.property) : undefined;
             if (desc) {
                 requestBody.description = requestBody.description
@@ -1049,67 +906,67 @@ function createOAPIEmitter(context, options) {
             }
             const contentTypes = body.contentTypes.length > 0 ? body.contentTypes : ["application/json"];
             for (const contentType of contentTypes) {
-                const { schema: bodySchema } = getBodyContentEntry(operation, "request", body, visibility, contentType);
-                if (schemaMap.has(contentType)) {
-                    schemaMap.get(contentType).push(bodySchema);
+                const existing = schemaMap.get(contentType);
+                const entry = getBodyContentEntry(body, visibility, contentType, examples.requestBody[contentType]);
+                if (existing) {
+                    existing.push(entry);
                 }
                 else {
-                    schemaMap.set(contentType, [bodySchema]);
+                    schemaMap.set(contentType, [entry]);
                 }
             }
         }
-        const content = {};
         for (const [contentType, schemaArray] of schemaMap) {
             if (schemaArray.length === 1) {
-                content[contentType] = { schema: schemaArray[0] };
+                requestBody.content[contentType] = schemaArray[0];
             }
             else {
-                content[contentType] = {
-                    schema: { anyOf: schemaArray },
+                requestBody.content[contentType] = {
+                    schema: { anyOf: schemaArray.map((x) => x.schema).filter((x) => x !== undefined) },
+                    encoding: schemaArray.find((x) => x.encoding)?.encoding,
                 };
             }
         }
-        requestBody.content = content;
-        currentEndpoint.requestBody = requestBody;
+        return requestBody;
     }
-    function emitRequestBody(operation, body, visibility) {
-        if (body === undefined || isVoidType(body.type)) {
-            return;
+    function getParameterOrRef(parameter, visibility) {
+        if (isNeverType(parameter.param.type)) {
+            return undefined;
         }
-        const requestBody = {
-            description: body.property ? getDoc(program, body.property) : undefined,
-            required: body.property ? !body.property.optional : true,
-            content: {},
-        };
-        const contentTypes = body.contentTypes.length > 0 ? body.contentTypes : ["application/json"];
-        for (const contentType of contentTypes) {
-            requestBody.content[contentType] = getBodyContentEntry(operation, "request", body, visibility, contentType);
+        let spreadParam = false;
+        let property = parameter.param;
+        if (property.sourceProperty) {
+            // chase our sources all the way back to the first place this property
+            // was defined.
+            spreadParam = true;
+            property = property.sourceProperty;
+            while (property.sourceProperty) {
+                property = property.sourceProperty;
+            }
         }
-        currentEndpoint.requestBody = requestBody;
-    }
-    function emitParameter(parameter, visibility) {
-        if (isNeverType(parameter.param.type)) {
-            return;
+        const refUrl = getRef(program, property);
+        if (refUrl) {
+            return {
+                $ref: refUrl,
+            };
         }
-        const existing = currentEndpoint.parameters.find((p) => p.name === parameter.name && p.in === parameter.type);
-        if (existing) {
-            populateParameter(existing, parameter, visibility);
+        if (params.has(property)) {
+            return params.get(property);
         }
-        else {
-            const ph = getParamPlaceholder(parameter.param);
-            currentEndpoint.parameters.push(ph);
-            // If the parameter already has a $ref, don't bother populating it
-            if (!("$ref" in ph)) {
-                populateParameter(ph, parameter, visibility);
-            }
+        const param = getParameter(parameter, visibility);
+        // only parameters inherited by spreading from non-inlined type are shared in #/components/parameters
+        if (spreadParam && property.model && !shouldInline(program, property.model)) {
+            params.set(property, param);
+            paramModels.add(property.model);
         }
+        return param;
     }
     function getOpenAPIParameterBase(param, visibility) {
         const typeSchema = getSchemaForType(param.type, visibility);
         if (!typeSchema) {
             return undefined;
         }
-        const schema = applyEncoding(param, applyIntrinsicDecorators(param, typeSchema));
+        const schema = applyEncoding(program, param, applyIntrinsicDecorators(param, typeSchema), options);
         if (param.defaultValue) {
             schema.default = getDefaultValue(program, param.defaultValue);
         }
@@ -1123,35 +980,18 @@ function createOAPIEmitter(context, options) {
         attachExtensions(program, param, oaiParam);
         return oaiParam;
     }
-    function mergeOpenApiParameters(param, base) {
-        if (param.schema) {
-            const schema = param.schema;
-            if (schema.enum && base.schema.enum) {
-                schema.enum = [...new Set([...schema.enum, ...base.schema.enum])];
+    function mergeOpenApiParameters(target, apply) {
+        if (target.schema) {
+            const schema = target.schema;
+            if (schema.enum && apply.schema.enum) {
+                schema.enum = [...new Set([...schema.enum, ...apply.schema.enum])];
             }
-            param.schema = schema;
+            target.schema = schema;
         }
         else {
-            Object.assign(param, base);
-        }
-        return param;
-    }
-    function populateParameter(ph, parameter, visibility) {
-        ph.name = parameter.name;
-        ph.in = parameter.type;
-        const paramBase = getOpenAPIParameterBase(parameter.param, visibility);
-        if (paramBase) {
-            ph = mergeOpenApiParameters(ph, paramBase);
-        }
-        const format = mapParameterFormat(parameter);
-        if (format === undefined) {
-            ph.schema = {
-                type: "string",
-            };
-        }
-        else {
-            Object.assign(ph, format);
+            Object.assign(target, apply);
         }
+        return target;
     }
     function mapParameterFormat(parameter) {
         switch (parameter.type) {
@@ -1332,44 +1172,6 @@ function createOAPIEmitter(context, options) {
         attachExtensions(program, typespecType, newTarget);
         return newTarget;
     }
-    function applyEncoding(typespecType, target) {
-        const encodeData = getEncode(program, typespecType);
-        if (encodeData) {
-            const newTarget = { ...target };
-            const newType = callSchemaEmitter(encodeData.type, Visibility.Read, false, "application/json");
-            newTarget.type = newType.type;
-            // If the target already has a format it takes priority. (e.g. int32)
-            newTarget.format = mergeFormatAndEncoding(newTarget.format, encodeData.encoding, newType.format);
-            return newTarget;
-        }
-        return target;
-    }
-    function mergeFormatAndEncoding(format, encoding, encodeAsFormat) {
-        switch (format) {
-            case undefined:
-                return encodeAsFormat ?? encoding;
-            case "date-time":
-                switch (encoding) {
-                    case "rfc3339":
-                        return "date-time";
-                    case "unixTimestamp":
-                        return "unixtime";
-                    case "rfc7231":
-                        return "http-date";
-                    default:
-                        return encoding;
-                }
-            case "duration":
-                switch (encoding) {
-                    case "ISO8601":
-                        return "duration";
-                    default:
-                        return encodeAsFormat ?? encoding;
-                }
-            default:
-                return encodeAsFormat ?? encoding;
-        }
-    }
     function applyExternalDocs(typespecType, target) {
         const externalDocs = getExternalDocs(program, typespecType);
         if (externalDocs) {
@@ -1405,14 +1207,15 @@ function createOAPIEmitter(context, options) {
         });
         return security;
     }
-    function emitEndpointSecurity(authReference) {
+    function getEndpointSecurity(authReference) {
         const security = getOpenAPISecurity(authReference);
         if (deepEquals(security, root.security)) {
-            return;
+            return undefined;
         }
         if (security.length > 0) {
-            currentEndpoint.security = security;
+            return security;
         }
+        return undefined;
     }
     function getOpenAPI3Scheme(auth) {
         const scheme = getOpenAPI3SchemeInternal(auth);