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

package/dist/src/openapi.js

@@ -1,11 +1,12 @@
-import { compilerAssert, emitFile, getAllTags, getAnyExtensionFromPath, getDoc, getEncode, getFormat, getKnownValues, getMaxItems, getMaxLength, getMaxValue, getMaxValueExclusive, getMinItems, getMinLength, getMinValue, getMinValueExclusive, getNamespaceFullName, getPattern, getService, getSummary, ignoreDiagnostics, interpolatePath, isArrayModelType, isDeprecated, isGlobalNamespace, isNeverType, isNullType, isSecret, isVoidType, listServices, navigateTypesInNamespace, projectProgram, resolvePath, } from "@typespec/compiler";
-import { createMetadataInfo, getAuthentication, getHttpService, getServers, getStatusCodeDescription, isContentTypeHeader, isOverloadSameEndpoint, reportIfNoRoutes, resolveRequestVisibility, Visibility, } from "@typespec/http";
-import { getExtensions, getExternalDocs, getInfo, getOpenAPITypeName, getParameterKey, isDefaultResponse, isReadonlyProperty, resolveOperationId, shouldInline, } from "@typespec/openapi";
+import { compilerAssert, createDiagnosticCollector, emitFile, getAllTags, getAnyExtensionFromPath, getDoc, getEncode, 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, isOverloadSameEndpoint, reportIfNoRoutes, resolveAuthentication, resolveRequestVisibility, Visibility, } from "@typespec/http";
+import { getExtensions, getExternalDocs, getOpenAPITypeName, getParameterKey, isDefaultResponse, isReadonlyProperty, resolveInfo, resolveOperationId, shouldInline, } from "@typespec/openapi";
 import { buildVersionProjections } from "@typespec/versioning";
 import { stringify } from "yaml";
 import { getRef } from "./decorators.js";
-import { reportDiagnostic } from "./lib.js";
-import { OpenAPI3SchemaEmitter } from "./schema-emitter.js";
+import { createDiagnostic } from "./lib.js";
+import { getDefaultValue, OpenAPI3SchemaEmitter } from "./schema-emitter.js";
 import { deepEquals } from "./util.js";
 import { resolveVisibilityUsage } from "./visibility-usage.js";
 const defaultFileType = "yaml";
@@ -13,12 +14,35 @@ const defaultOptions = {
     "new-line": "lf",
     "omit-unreachable-types": false,
     "include-x-typespec-name": "never",
+    "safeint-strategy": "int64",
 };
 export async function $onEmit(context) {
     const options = resolveOptions(context);
     const emitter = createOAPIEmitter(context, options);
     await emitter.emitOpenAPI();
 }
+/**
+ * Get the OpenAPI 3 document records from the given program. The documents are
+ * returned as a JS object.
+ *
+ * @param program The program to emit to OpenAPI 3
+ * @param options OpenAPI 3 emit options
+ * @returns An array of OpenAPI 3 document records.
+ */
+export async function getOpenAPI3(program, options = {}) {
+    const context = {
+        program,
+        // this value doesn't matter for getting the OpenAPI3 objects
+        emitterOutputDir: "tsp-output",
+        options: options,
+        getAssetEmitter(TypeEmitterClass) {
+            return createAssetEmitter(program, TypeEmitterClass, this);
+        },
+    };
+    const resolvedOptions = resolveOptions(context);
+    const emitter = createOAPIEmitter(context, resolvedOptions);
+    return emitter.getOpenAPI();
+}
 function findFileTypeFromFilename(filename) {
     if (filename === undefined) {
         return defaultFileType;
@@ -43,6 +67,7 @@ export function resolveOptions(context) {
         newLine: resolvedOptions["new-line"],
         omitUnreachableTypes: resolvedOptions["omit-unreachable-types"],
         includeXTypeSpecName: resolvedOptions["include-x-typespec-name"],
+        safeintStrategy: resolvedOptions["safeint-strategy"],
         outputFile: resolvePath(context.emitterOutputDir, outputFile),
     };
 }
@@ -50,6 +75,7 @@ function createOAPIEmitter(context, options) {
     let program = context.program;
     let schemaEmitter;
     let root;
+    let diagnostics;
     let currentService;
     // Get the service namespace string for use in name shortening
     let serviceNamespaceName;
@@ -73,9 +99,45 @@ function createOAPIEmitter(context, options) {
             return name !== serviceNamespaceName;
         },
     };
-    return { emitOpenAPI };
-    function initializeEmitter(service, version) {
-        var _a, _b, _c;
+    return { emitOpenAPI, getOpenAPI };
+    async function emitOpenAPI() {
+        const services = await getOpenAPI();
+        // first, emit diagnostics
+        for (const serviceRecord of services) {
+            if (serviceRecord.versioned) {
+                for (const documentRecord of serviceRecord.versions) {
+                    program.reportDiagnostics(documentRecord.diagnostics);
+                }
+            }
+            else {
+                program.reportDiagnostics(serviceRecord.diagnostics);
+            }
+        }
+        if (program.compilerOptions.noEmit || program.hasError()) {
+            return;
+        }
+        const multipleService = services.length > 1;
+        for (const serviceRecord of services) {
+            if (serviceRecord.versioned) {
+                for (const documentRecord of serviceRecord.versions) {
+                    await emitFile(program, {
+                        path: resolveOutputFile(serviceRecord.service, multipleService, documentRecord.version),
+                        content: serializeDocument(documentRecord.document, options.fileType),
+                        newLine: options.newLine,
+                    });
+                }
+            }
+            else {
+                await emitFile(program, {
+                    path: resolveOutputFile(serviceRecord.service, multipleService),
+                    content: serializeDocument(serviceRecord.document, options.fileType),
+                    newLine: options.newLine,
+                });
+            }
+        }
+    }
+    function initializeEmitter(service, allHttpAuthentications, defaultAuth, version) {
+        var _a;
         currentService = service;
         metadataInfo = createMetadataInfo(program, {
             canonicalVisibility: Visibility.Read,
@@ -87,28 +149,30 @@ function createOAPIEmitter(context, options) {
                 super(emitter, metadataInfo, visibilityUsage, options);
             }
         });
-        const auth = processAuth(service.type);
+        const securitySchemes = getOpenAPISecuritySchemes(allHttpAuthentications);
+        const security = getOpenAPISecurity(defaultAuth);
+        const info = resolveInfo(program, service.type);
         root = {
             openapi: "3.0.0",
             info: {
-                title: (_a = service.title) !== null && _a !== void 0 ? _a : "(title)",
-                version: (_b = version !== null && version !== void 0 ? version : service.version) !== null && _b !== void 0 ? _b : "0000-00-00",
-                description: getDoc(program, service.type),
-                ...getInfo(program, service.type),
+                title: "(title)",
+                ...info,
+                version: (_a = version !== null && version !== void 0 ? version : info === null || info === void 0 ? void 0 : info.version) !== null && _a !== void 0 ? _a : "0.0.0",
             },
             externalDocs: getExternalDocs(program, service.type),
             tags: [],
             paths: {},
-            security: auth === null || auth === void 0 ? void 0 : auth.security,
+            security: security.length > 0 ? security : undefined,
             components: {
                 parameters: {},
                 requestBodies: {},
                 responses: {},
                 schemas: {},
                 examples: {},
-                securitySchemes: (_c = auth === null || auth === void 0 ? void 0 : auth.securitySchemes) !== null && _c !== void 0 ? _c : {},
+                securitySchemes: securitySchemes,
             },
         };
+        diagnostics = createDiagnosticCollector();
         const servers = getServers(program, service.type);
         if (servers) {
             root.servers = resolveServers(servers);
@@ -140,11 +204,11 @@ function createOAPIEmitter(context, options) {
     function validateValidServerVariable(program, prop) {
         const isValid = isValidServerVariableType(program, prop.type);
         if (!isValid) {
-            reportDiagnostic(program, {
+            diagnostics.add(createDiagnostic({
                 code: "invalid-server-variable",
                 format: { propName: prop.name },
                 target: prop,
-            });
+            }));
         }
         return isValid;
     }
@@ -156,7 +220,7 @@ function createOAPIEmitter(context, options) {
                     continue;
                 }
                 const variable = {
-                    default: prop.default ? getDefaultValue(prop.type, prop.default) : "",
+                    default: prop.default ? getDefaultValue(program, prop.type, prop.default) : "",
                     description: getDoc(program, prop),
                 };
                 if (prop.type.kind === "Enum") {
@@ -180,12 +244,53 @@ function createOAPIEmitter(context, options) {
             };
         });
     }
-    async function emitOpenAPI() {
+    async function getOpenAPI() {
+        const serviceRecords = [];
         const services = listServices(program);
         if (services.length === 0) {
             services.push({ type: program.getGlobalNamespaceType() });
         }
         for (const service of services) {
+            const versions = buildVersionProjections(program, service.type);
+            if (versions.length === 1 && versions[0].version === undefined) {
+                // non-versioned spec
+                const document = await getProjectedOpenAPIDocument(service, versions[0]);
+                if (document === undefined) {
+                    // an error occurred producing this document, so don't return it
+                    return serviceRecords;
+                }
+                serviceRecords.push({
+                    service,
+                    versioned: false,
+                    document: document[0],
+                    diagnostics: document[1],
+                });
+            }
+            else {
+                // versioned spec
+                const serviceRecord = {
+                    service,
+                    versioned: true,
+                    versions: [],
+                };
+                serviceRecords.push(serviceRecord);
+                for (const record of versions) {
+                    const document = await getProjectedOpenAPIDocument(service, record);
+                    if (document === undefined) {
+                        // an error occurred producing this document
+                        continue;
+                    }
+                    serviceRecord.versions.push({
+                        service,
+                        version: record.version,
+                        document: document[0],
+                        diagnostics: document[1],
+                    });
+                }
+            }
+        }
+        return serviceRecords;
+        async function getProjectedOpenAPIDocument(service, record) {
             const commonProjections = [
                 {
                     projectionName: "target",
@@ -193,17 +298,15 @@ function createOAPIEmitter(context, options) {
                 },
             ];
             const originalProgram = program;
-            const versions = buildVersionProjections(program, service.type);
-            for (const record of versions) {
-                const projectedProgram = (program = projectProgram(originalProgram, [
-                    ...commonProjections,
-                    ...record.projections,
-                ]));
-                const projectedServiceNs = projectedProgram.projector.projectedTypes.get(service.type);
-                await emitOpenAPIFromVersion(projectedServiceNs === projectedProgram.getGlobalNamespaceType()
-                    ? { type: projectedProgram.getGlobalNamespaceType() }
-                    : getService(program, projectedServiceNs), services.length > 1, record.version);
-            }
+            const projectedProgram = (program = projectProgram(originalProgram, [
+                ...commonProjections,
+                ...record.projections,
+            ]));
+            const projectedServiceNs = projectedProgram.projector.projectedTypes.get(service.type);
+            const document = await getOpenApiFromVersion(projectedServiceNs === projectedProgram.getGlobalNamespaceType()
+                ? { type: projectedProgram.getGlobalNamespaceType() }
+                : getService(program, projectedServiceNs), record.version);
+            return document;
         }
     }
     function resolveOutputFile(service, multipleService, version) {
@@ -297,11 +400,11 @@ function createOAPIEmitter(context, options) {
         }
     }
     function rangeToOpenAPI(range, diagnosticTarget) {
-        const reportInvalid = () => reportDiagnostic(program, {
+        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;
@@ -372,6 +475,7 @@ function createOAPIEmitter(context, options) {
                 parameters: [],
             },
             bodies: undefined,
+            authentication: operations[0].authentication,
             responses: new Map(),
         };
         for (const [paramName, ops] of paramMap) {
@@ -413,17 +517,20 @@ function createOAPIEmitter(context, options) {
         }
         return result;
     }
-    async function emitOpenAPIFromVersion(service, multipleService, version) {
-        initializeEmitter(service, version);
+    async function getOpenApiFromVersion(service, version) {
         try {
             const httpService = ignoreDiagnostics(getHttpService(program, service.type));
+            const auth = resolveAuthentication(httpService);
+            initializeEmitter(service, auth.schemes, auth.defaultAuth, version);
             reportIfNoRoutes(program, httpService.operations);
             for (const op of resolveOperations(httpService.operations)) {
                 if (op.kind === "shared") {
-                    emitSharedOperation(op);
+                    const opAuth = auth.operationsAuth.get(op.operations[0]);
+                    emitSharedOperation(op, opAuth);
                 }
                 else {
-                    emitOperation(op);
+                    const opAuth = auth.operationsAuth.get(op.operation);
+                    emitOperation(op, opAuth);
                 }
             }
             emitParameters();
@@ -437,14 +544,7 @@ function createOAPIEmitter(context, options) {
                     }
                 }
             }
-            if (!program.compilerOptions.noEmit && !program.hasError()) {
-                // Write out the OpenAPI document to the output path
-                await emitFile(program, {
-                    path: resolveOutputFile(service, multipleService, version),
-                    content: serializeDocument(root, options.fileType),
-                    newLine: options.newLine,
-                });
-            }
+            return [root, diagnostics.diagnostics];
         }
         catch (err) {
             if (err instanceof ErrorTypeFoundError) {
@@ -468,7 +568,7 @@ function createOAPIEmitter(context, options) {
             return undefined;
         }
     }
-    function emitSharedOperation(shared) {
+    function emitSharedOperation(shared, authReference) {
         const { path: fullPath, verb: verb, operations: ops } = shared;
         if (!root.paths[fullPath]) {
             root.paths[fullPath] = {};
@@ -510,10 +610,10 @@ function createOAPIEmitter(context, options) {
             return resolveRequestVisibility(program, op, verb);
         });
         if (visibilities.some((v) => v !== visibilities[0])) {
-            reportDiagnostic(program, {
+            diagnostics.add(createDiagnostic({
                 code: "inconsistent-shared-route-request-visibility",
                 target: ops[0],
-            });
+            }));
         }
         const visibility = resolveRequestVisibility(program, shared.operations[0], verb);
         emitEndpointParameters(shared.parameters.parameters, visibility);
@@ -532,12 +632,15 @@ function createOAPIEmitter(context, options) {
             }
             attachExtensions(program, op, currentEndpoint);
         }
+        if (authReference) {
+            emitSecurity(authReference);
+        }
     }
-    function emitOperation(operation) {
+    function emitOperation(operation, authReference) {
         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) {
-            reportDiagnostic(program, { code: "path-query", target: op });
+            diagnostics.add(createDiagnostic({ code: "path-query", target: op }));
             return;
         }
         if (!root.paths[fullPath]) {
@@ -567,6 +670,9 @@ function createOAPIEmitter(context, options) {
         emitEndpointParameters(parameters.parameters, visibility);
         emitRequestBody(parameters.body, visibility);
         emitResponses(operation.responses);
+        if (authReference) {
+            emitSecurity(authReference);
+        }
         if (isDeprecated(program, op)) {
             currentEndpoint.deprecated = true;
         }
@@ -636,11 +742,11 @@ function createOAPIEmitter(context, options) {
                     const existing = obj.headers[key];
                     if (existing) {
                         if (!deepEquals(existing, headerVal)) {
-                            reportDiagnostic(program, {
+                            diagnostics.add(createDiagnostic({
                                 code: "duplicate-header",
                                 format: { header: key },
                                 target: target,
-                            });
+                            }));
                         }
                         continue;
                     }
@@ -699,11 +805,11 @@ function createOAPIEmitter(context, options) {
             case "declaration":
                 return { $ref: `#/components/schemas/${result.name}` };
             case "circular":
-                reportDiagnostic(program, {
+                diagnostics.add(createDiagnostic({
                     code: "inline-cycle",
                     format: { type: getOpenAPITypeName(program, type, typeNameOptions) },
                     target: type,
-                });
+                }));
                 return {};
             case "none":
                 return {};
@@ -716,11 +822,11 @@ function createOAPIEmitter(context, options) {
             case "declaration":
                 return result.value;
             case "circular":
-                reportDiagnostic(program, {
+                diagnostics.add(createDiagnostic({
                     code: "inline-cycle",
                     format: { type: getOpenAPITypeName(program, type, typeNameOptions) },
                     target: type,
-                });
+                }));
                 return {};
             case "none":
                 return {};
@@ -869,7 +975,7 @@ function createOAPIEmitter(context, options) {
         }
         const schema = applyEncoding(param, applyIntrinsicDecorators(param, typeSchema));
         if (param.default) {
-            schema.default = getDefaultValue(param.type, param.default);
+            schema.default = getDefaultValue(program, param.type, param.default);
         }
         // Description is already provided in the parameter itself.
         delete schema.description;
@@ -929,14 +1035,14 @@ function createOAPIEmitter(context, options) {
             case "simple":
                 return { style: "simple" };
             default:
-                reportDiagnostic(program, {
+                diagnostics.add(createDiagnostic({
                     code: "invalid-format",
                     format: {
                         paramType: "header",
                         value: parameter.format,
                     },
                     target: parameter.param,
-                });
+                }));
                 return undefined;
         }
     }
@@ -955,14 +1061,14 @@ function createOAPIEmitter(context, options) {
             case "pipes":
                 return { style: "pipeDelimited", explode: false };
             default:
-                reportDiagnostic(program, {
+                diagnostics.add(createDiagnostic({
                     code: "invalid-format",
                     format: {
                         paramType: "query",
                         value: parameter.format,
                     },
                     target: parameter.param,
-                });
+                }));
                 return undefined;
         }
     }
@@ -1014,41 +1120,6 @@ function createOAPIEmitter(context, options) {
     function getSchemaForType(type, visibility) {
         return callSchemaEmitter(type, visibility);
     }
-    function getDefaultValue(type, defaultType) {
-        var _a;
-        switch (defaultType.kind) {
-            case "String":
-                return defaultType.value;
-            case "Number":
-                return defaultType.value;
-            case "Boolean":
-                return defaultType.value;
-            case "Tuple":
-                compilerAssert(type.kind === "Tuple" || (type.kind === "Model" && isArrayModelType(program, type)), "setting tuple default to non-tuple value");
-                if (type.kind === "Tuple") {
-                    return defaultType.values.map((defaultTupleValue, index) => getDefaultValue(type.values[index], defaultTupleValue));
-                }
-                else {
-                    return defaultType.values.map((defaultTuplevalue) => getDefaultValue(type.indexer.value, defaultTuplevalue));
-                }
-            case "Intrinsic":
-                return isNullType(defaultType)
-                    ? null
-                    : reportDiagnostic(program, {
-                        code: "invalid-default",
-                        format: { type: defaultType.kind },
-                        target: defaultType,
-                    });
-            case "EnumMember":
-                return (_a = defaultType.value) !== null && _a !== void 0 ? _a : defaultType.name;
-            default:
-                reportDiagnostic(program, {
-                    code: "invalid-default",
-                    format: { type: defaultType.kind },
-                    target: defaultType,
-                });
-        }
-    }
     function attachExtensions(program, type, emitObject) {
         // Attach any OpenAPI extensions
         const extensions = getExtensions(program, type);
@@ -1166,41 +1237,47 @@ function createOAPIEmitter(context, options) {
             target.externalDocs = externalDocs;
         }
     }
-    function processAuth(serviceNamespace) {
-        const authentication = getAuthentication(program, serviceNamespace);
-        if (authentication) {
-            return processServiceAuthentication(authentication);
+    function getOpenAPISecuritySchemes(httpAuthentications) {
+        const schemes = {};
+        for (const httpAuth of httpAuthentications) {
+            const scheme = getOpenAPI3Scheme(httpAuth);
+            if (scheme) {
+                schemes[httpAuth.id] = scheme;
+            }
         }
-        return undefined;
+        return schemes;
     }
-    function processServiceAuthentication(authentication) {
-        const oaiSchemes = {};
-        const security = [];
-        for (const option of authentication.options) {
-            const oai3SecurityOption = {};
-            for (const scheme of option.schemes) {
-                const result = getOpenAPI3Scheme(scheme);
-                if (result) {
-                    oaiSchemes[scheme.id] = result.scheme;
-                    oai3SecurityOption[scheme.id] = result.scopes;
+    function getOpenAPISecurity(authReference) {
+        const security = authReference.options.map((authOption) => {
+            const securityOption = {};
+            for (const httpAuthRef of authOption.all) {
+                switch (httpAuthRef.kind) {
+                    case "noAuth":
+                        // should emit "{}" as a security option https://github.com/OAI/OpenAPI-Specification/issues/14#issuecomment-297457320
+                        continue;
+                    case "oauth2":
+                        securityOption[httpAuthRef.auth.id] = httpAuthRef.scopes;
+                        continue;
+                    default:
+                        securityOption[httpAuthRef.auth.id] = [];
                 }
             }
-            security.push(oai3SecurityOption);
+            return securityOption;
+        });
+        return security;
+    }
+    function emitSecurity(authReference) {
+        const security = getOpenAPISecurity(authReference);
+        if (security.length > 0) {
+            currentEndpoint.security = security;
         }
-        return { securitySchemes: oaiSchemes, security };
     }
     function getOpenAPI3Scheme(auth) {
         switch (auth.type) {
             case "http":
-                return {
-                    scheme: { type: "http", scheme: auth.scheme, description: auth.description },
-                    scopes: [],
-                };
+                return { type: "http", scheme: auth.scheme, description: auth.description };
             case "apiKey":
-                return {
-                    scheme: { type: "apiKey", in: auth.in, name: auth.name, description: auth.description },
-                    scopes: [],
-                };
+                return { type: "apiKey", in: auth.in, name: auth.name, description: auth.description };
             case "oauth2":
                 const flows = {};
                 const scopes = [];
@@ -1213,22 +1290,21 @@ function createOAPIEmitter(context, options) {
                         scopes: Object.fromEntries(flow.scopes.map((x) => { var _a; return [x.value, (_a = x.description) !== null && _a !== void 0 ? _a : ""]; })),
                     };
                 }
-                return { scheme: { type: "oauth2", flows, description: auth.description }, scopes };
+                return { type: "oauth2", flows, description: auth.description };
             case "openIdConnect":
                 return {
-                    scheme: {
-                        type: "openIdConnect",
-                        openIdConnectUrl: auth.openIdConnectUrl,
-                        description: auth.description,
-                    },
-                    scopes: [],
+                    type: "openIdConnect",
+                    openIdConnectUrl: auth.openIdConnectUrl,
+                    description: auth.description,
                 };
+            case "noAuth":
+                return undefined;
             default:
-                reportDiagnostic(program, {
+                diagnostics.add(createDiagnostic({
                     code: "unsupported-auth",
                     format: { authType: auth.type },
                     target: currentService.type,
-                });
+                }));
                 return undefined;
         }
     }