From 90346d89fbbd4d301c9bdb722385d3ad51d3d75b Mon Sep 17 00:00:00 2001 From: Yashvardhan Thanvi Date: Mon, 19 Oct 2026 11:24:00 +0530 Subject: [PATCH 1/3] fix(openapi3): use the first enum value as the server variable default A server variable typed as an enum, a union of string literals or a string literal was emitted with `default: ""` next to its `enum` when the TypeSpec property had no default. OpenAPI 3.1 and later require the default to be one of the enum values (3.0 recommends it), so the emitted document was invalid. When there is no explicit default and an enum was computed, use the first enum value. A variable typed as the service's versions enum uses the version of the document being emitted instead, so each versioned document defaults to its own version. Explicit defaults and plain string variables are unchanged. The emitter shares this code for every OpenAPI version, so 3.0, 3.1 and 3.2 all get the same output. --- ...ariable-enum-default-2026-9-19-11-21-11.md | 7 ++ packages/openapi3/src/openapi.ts | 24 ++++- packages/openapi3/test/servers.test.ts | 95 ++++++++++++++++++- 3 files changed, 118 insertions(+), 8 deletions(-) create mode 100644 .chronus/changes/fix-openapi3-server-variable-enum-default-2026-9-19-11-21-11.md diff --git a/.chronus/changes/fix-openapi3-server-variable-enum-default-2026-9-19-11-21-11.md b/.chronus/changes/fix-openapi3-server-variable-enum-default-2026-9-19-11-21-11.md new file mode 100644 index 00000000000..596514400f9 --- /dev/null +++ b/.chronus/changes/fix-openapi3-server-variable-enum-default-2026-9-19-11-21-11.md @@ -0,0 +1,7 @@ +--- +changeKind: fix +packages: + - "@typespec/openapi3" +--- + +Server variables that have an `enum` but no default now use the first `enum` value as their `default` instead of an empty string, since OpenAPI 3.1 and later require the default to be one of the `enum` values. A server variable typed as the service's versions enum uses the version of each emitted document instead. diff --git a/packages/openapi3/src/openapi.ts b/packages/openapi3/src/openapi.ts index 482c95d69ef..65273dfb533 100644 --- a/packages/openapi3/src/openapi.ts +++ b/packages/openapi3/src/openapi.ts @@ -137,6 +137,7 @@ import { isBytesKeptRaw, isSharedHttpOperation, } from "./util.js"; +import type { VersioningModule } from "./versioning-module.js"; import { resolveVersioningModule } from "./versioning-module.js"; import type { VisibilityUsageTracker } from "./visibility-usage.js"; import { resolveVisibilityUsage } from "./visibility-usage.js"; @@ -347,6 +348,7 @@ function createOAPIEmitter( let visibilityUsage: VisibilityUsageTracker; let sseModule: SSEModule | undefined; let jsonSchemaModule: JsonSchemaModule | undefined; + let versioningModule: VersioningModule | undefined; // Map model properties that represent shared parameters to their parameter // definition that will go in #/components/parameters. Inlined parameters do not go in @@ -500,7 +502,7 @@ function createOAPIEmitter( const servers = getServers(program, service.type); if (servers) { - root.servers = resolveServers(servers); + root.servers = resolveServers(servers, version); } attachExtensions(program, service.type, root); @@ -547,7 +549,13 @@ function createOAPIEmitter( return isValid; } - function resolveServers(servers: HttpServer[]): OpenAPI3Server[] { + /** Whether `type` is the enum passed to `@versioned` on the current service. */ + function isServiceVersionsEnum(type: Type): boolean { + const versionMap = versioningModule?.getVersion(program, currentService.type); + return versionMap?.getVersions().some((v) => v.enumMember.enum === type) ?? false; + } + + function resolveServers(servers: HttpServer[], version?: string): OpenAPI3Server[] { return servers.map((server) => { const variables: Record = {}; for (const [name, prop] of server.parameters) { @@ -569,6 +577,16 @@ function createOAPIEmitter( } else if (prop.type.kind === "String") { variable.enum = [prop.type.value]; } + // OpenAPI requires `default` to be one of the `enum` values. Use the version being + // emitted for the versions enum, and the first value otherwise. + if (!prop.defaultValue && variable.enum?.length) { + variable.default = + version !== undefined && + variable.enum.includes(version) && + isServiceVersionsEnum(prop.type) + ? version + : variable.enum[0]; + } attachExtensions(program, prop, variable); variables[name] = variable; } @@ -581,7 +599,7 @@ function createOAPIEmitter( } async function getOpenAPI(): Promise { - const versioningModule = await resolveVersioningModule(); + versioningModule = await resolveVersioningModule(); const serviceRecords: OpenAPI3ServiceRecord[] = []; const services = listServices(program); if (services.length === 0) { diff --git a/packages/openapi3/test/servers.test.ts b/packages/openapi3/test/servers.test.ts index 321fd7645b5..b78373720c1 100644 --- a/packages/openapi3/test/servers.test.ts +++ b/packages/openapi3/test/servers.test.ts @@ -1,9 +1,10 @@ import { expectDiagnostics } from "@typespec/compiler/testing"; import { deepStrictEqual } from "assert"; import { it } from "vitest"; +import { openApiForVersions } from "./test-host.js"; import { supportedVersions, worksFor } from "./works-for.js"; -worksFor(supportedVersions, ({ diagnoseOpenApiFor, openApiFor }) => { +worksFor(supportedVersions, ({ diagnoseOpenApiFor, openApiFor, version: specVersion }) => { it("set a basic server(url)", async () => { const res = await openApiFor( ` @@ -87,7 +88,31 @@ worksFor(supportedVersions, ({ diagnoseOpenApiFor, openApiFor }) => { } `, ); - deepStrictEqual(res.servers[0].variables.region.enum, ["westus", "eastus"]); + deepStrictEqual(res.servers[0].variables.region, { + default: "westus", + enum: ["westus", "eastus"], + }); + }); + + it("keeps an explicit default for an enum whose members are encoded as strings", async () => { + const res = await openApiFor( + ` + @service(#{title: "My service"}) + @server("https://{region}.example.com", "Regional account endpoint", {region?: Region = Region.eastUs}) + namespace MyService {} + + enum Region { + @encodedName("application/json", "westus") + westUs: 1, + @encodedName("application/json", "eastus") + eastUs: 2, + } + `, + ); + deepStrictEqual(res.servers[0].variables.region, { + default: "eastus", + enum: ["westus", "eastus"], + }); }); it("emit diagnostic when a numeric enum member is left unencoded", async () => { @@ -227,12 +252,28 @@ worksFor(supportedVersions, ({ diagnoseOpenApiFor, openApiFor }) => { description: "Regional account endpoint", url: "https://{region}.example.com", variables: { - region: { default: "", enum: ["westus", "eastus"] }, + region: { default: "westus", enum: ["westus", "eastus"] }, }, }, ]); }); + it("set a server with enum properties with a default", async () => { + const res = await openApiFor( + ` + enum Region { westus, eastus } + @service(#{title: "My service"}) + @server("https://{region}.example.com", "Regional account endpoint", { + region?: Region = Region.eastus, + }) + namespace MyService {} + `, + ); + deepStrictEqual(res.servers[0].variables, { + region: { default: "eastus", enum: ["westus", "eastus"] }, + }); + }); + it("set a server with string literal", async () => { const res = await openApiFor( ` @@ -249,7 +290,7 @@ worksFor(supportedVersions, ({ diagnoseOpenApiFor, openApiFor }) => { description: "Regional account endpoint", url: "https://{region}.example.com", variables: { - region: { default: "", enum: ["westus"] }, + region: { default: "westus", enum: ["westus"] }, }, }, ]); @@ -271,11 +312,55 @@ worksFor(supportedVersions, ({ diagnoseOpenApiFor, openApiFor }) => { description: "Regional account endpoint", url: "https://{region}.example.com", variables: { - region: { default: "", enum: ["westus", "eastus"] }, + region: { default: "westus", enum: ["westus", "eastus"] }, }, }, ]); }); + + it("set a server with unions type with a default", async () => { + const res = await openApiFor( + ` + @service(#{title: "My service"}) + @server("https://{region}.example.com", "Regional account endpoint", { + region?: "westus" | "eastus" = "eastus", + }) + namespace MyService {} + `, + ); + deepStrictEqual(res.servers[0].variables, { + region: { default: "eastus", enum: ["westus", "eastus"] }, + }); + }); + + it("set a server with the versions enum to the version of each document", async () => { + const documents = await openApiForVersions( + ` + @versioned(Versions) + @service(#{title: "My service"}) + @server("{endpoint}/{release}/{apiVersion}", "Versioned endpoint", { + endpoint: url, + release: Release, + apiVersion: Versions, + }) + namespace MyService { + enum Versions { v1: "2024-01-01", v2: "2025-01-01" } + // Same values as Versions, but not the versions enum, so it keeps the first value. + enum Release { previous: "2024-01-01", latest: "2025-01-01" } + } + `, + ["2024-01-01", "2025-01-01"], + { "openapi-versions": [specVersion] }, + ); + for (const [version, document] of Object.entries(documents)) { + deepStrictEqual(document.servers?.[0].variables, { + endpoint: { default: "" }, + release: { default: "2024-01-01", enum: ["2024-01-01", "2025-01-01"] }, + apiVersion: { default: version, enum: ["2024-01-01", "2025-01-01"] }, + }); + } + }); + it("set multiple servers", async () => { const res = await openApiFor( ` From 207198dca4363015d98cdba7dae07b893120f7b4 Mon Sep 17 00:00:00 2001 From: Yashvardhan Thanvi Date: Mon, 19 Oct 2026 23:47:06 +0530 Subject: [PATCH 2/3] fix(openapi3): warn when a server variable default falls back to the first enum value When a server variable can take more than one value and has no default, the emitter still uses the first value so the document stays valid, but now reports a missing-server-variable-default warning so the author can set the default they want. The versions enum case is not a guess and does not warn, and a variable with a single possible value does not warn either. The warning is reported once per parameter, not once per emitted version. --- ...ariable-enum-default-2026-9-19-11-21-11.md | 2 +- .../missing-server-variable-default.md | 20 ++++++ packages/openapi3/src/lib.ts | 7 ++ packages/openapi3/src/openapi.ts | 42 +++++++++++- packages/openapi3/test/servers.test.ts | 68 ++++++++++++++++--- 5 files changed, 126 insertions(+), 13 deletions(-) create mode 100644 packages/openapi3/src/diagnostics/missing-server-variable-default.md diff --git a/.chronus/changes/fix-openapi3-server-variable-enum-default-2026-9-19-11-21-11.md b/.chronus/changes/fix-openapi3-server-variable-enum-default-2026-9-19-11-21-11.md index 596514400f9..608415cdc79 100644 --- a/.chronus/changes/fix-openapi3-server-variable-enum-default-2026-9-19-11-21-11.md +++ b/.chronus/changes/fix-openapi3-server-variable-enum-default-2026-9-19-11-21-11.md @@ -4,4 +4,4 @@ packages: - "@typespec/openapi3" --- -Server variables that have an `enum` but no default now use the first `enum` value as their `default` instead of an empty string, since OpenAPI 3.1 and later require the default to be one of the `enum` values. A server variable typed as the service's versions enum uses the version of each emitted document instead. +Server variables that have an `enum` but no default now use the first `enum` value as their `default` instead of an empty string, since OpenAPI 3.1 and later require the default to be one of the `enum` values. A server variable typed as the service's versions enum uses the version of each emitted document instead. A new `missing-server-variable-default` warning is reported when that first value is used for a variable with more than one possible value. diff --git a/packages/openapi3/src/diagnostics/missing-server-variable-default.md b/packages/openapi3/src/diagnostics/missing-server-variable-default.md new file mode 100644 index 00000000000..1800a3f41ec --- /dev/null +++ b/packages/openapi3/src/diagnostics/missing-server-variable-default.md @@ -0,0 +1,20 @@ +This diagnostic is issued when a variable in the `@server` decorator can take more than one value (an enum or a union of string literals) but has no default. +OpenAPI requires the `default` of a server variable to be one of its `enum` values, so the emitter uses the first value. That value might not be the one you intended. + +To fix this issue, set a default on the server parameter. + +### Example + +```typespec +@server("https://{region}.example.com", "Regional endpoint", { + region: "westus" | "eastus", // No default, so "westus" is used +}) +``` + +Set a default to choose the value: + +```typespec +@server("https://{region}.example.com", "Regional endpoint", { + region?: "westus" | "eastus" = "eastus", +}) +``` diff --git a/packages/openapi3/src/lib.ts b/packages/openapi3/src/lib.ts index 0a13d99e4ef..f1d731075ec 100644 --- a/packages/openapi3/src/lib.ts +++ b/packages/openapi3/src/lib.ts @@ -337,6 +337,13 @@ export const $lib = createTypeSpecLibrary({ default: paramMessage`Server variable '${"propName"}' must be assignable to 'string'. It must either be a string, enum of string or union of strings.`, }, }, + "missing-server-variable-default": { + severity: "warning", + docs: fileRef.fromPackageRoot("src/diagnostics/missing-server-variable-default.md"), + messages: { + default: paramMessage`Server variable '${"propName"}' has no default, so '${"value"}', the first of its values, is used. Set a default on the parameter to choose a different one.`, + }, + }, "invalid-format": { severity: "warning", messages: { diff --git a/packages/openapi3/src/openapi.ts b/packages/openapi3/src/openapi.ts index 65273dfb533..1924efeb1bb 100644 --- a/packages/openapi3/src/openapi.ts +++ b/packages/openapi3/src/openapi.ts @@ -362,6 +362,14 @@ function createOAPIEmitter( // De-dupe the per-endpoint tags that will be added into the #/tags let tagsUsedInOperations: Set; + // Values already warned about for a server parameter with no default, keyed by its declaration. + // Servers are resolved once per document and each version of a versioned service gets its own + // copy of the parameter, so without this the same warning would be reported for every version. + const serverVariablesWarnedForDefault = new Map< + ModelProperty["node"] | ModelProperty, + Set + >(); + const typeNameOptions: TypeNameOptions = { // shorten type names by removing TypeSpec and service namespace namespaceFilter(ns) { @@ -555,6 +563,27 @@ function createOAPIEmitter( return versionMap?.getVersions().some((v) => v.enumMember.enum === type) ?? false; } + function reportMissingServerVariableDefault(prop: ModelProperty, value: string) { + // Template instances share a declaration but can have different values, so only skip a + // warning that was already reported for the same declaration and value. + const key = prop.node ?? prop; + let warnedValues = serverVariablesWarnedForDefault.get(key); + if (warnedValues === undefined) { + warnedValues = new Set(); + serverVariablesWarnedForDefault.set(key, warnedValues); + } else if (warnedValues.has(value)) { + return; + } + warnedValues.add(value); + diagnostics.add( + createDiagnostic({ + code: "missing-server-variable-default", + format: { propName: prop.name, value }, + target: prop, + }), + ); + } + function resolveServers(servers: HttpServer[], version?: string): OpenAPI3Server[] { return servers.map((server) => { const variables: Record = {}; @@ -580,12 +609,19 @@ function createOAPIEmitter( // OpenAPI requires `default` to be one of the `enum` values. Use the version being // emitted for the versions enum, and the first value otherwise. if (!prop.defaultValue && variable.enum?.length) { - variable.default = + if ( version !== undefined && variable.enum.includes(version) && isServiceVersionsEnum(prop.type) - ? version - : variable.enum[0]; + ) { + variable.default = version; + } else { + variable.default = variable.enum[0]; + // With more than one value the first one is only a guess, so tell the author. + if (variable.enum.length > 1) { + reportMissingServerVariableDefault(prop, variable.default); + } + } } attachExtensions(program, prop, variable); variables[name] = variable; diff --git a/packages/openapi3/test/servers.test.ts b/packages/openapi3/test/servers.test.ts index b78373720c1..09f42c65f5a 100644 --- a/packages/openapi3/test/servers.test.ts +++ b/packages/openapi3/test/servers.test.ts @@ -1,10 +1,20 @@ import { expectDiagnostics } from "@typespec/compiler/testing"; import { deepStrictEqual } from "assert"; import { it } from "vitest"; -import { openApiForVersions } from "./test-host.js"; +import { + emitOpenApiWithDiagnostics, + openApiForVersions, + TesterWithVersioning, +} from "./test-host.js"; import { supportedVersions, worksFor } from "./works-for.js"; worksFor(supportedVersions, ({ diagnoseOpenApiFor, openApiFor, version: specVersion }) => { + const missingDefaultWarning = (name: string, value: string) => ({ + code: "@typespec/openapi3/missing-server-variable-default", + severity: "warning" as const, + message: `Server variable '${name}' has no default, so '${value}', the first of its values, is used. Set a default on the parameter to choose a different one.`, + }); + it("set a basic server(url)", async () => { const res = await openApiFor( ` @@ -74,7 +84,7 @@ worksFor(supportedVersions, ({ diagnoseOpenApiFor, openApiFor, version: specVers }); it("accepts an enum whose numeric members are all encoded as strings", async () => { - const res = await openApiFor( + const [res, diagnostics] = await emitOpenApiWithDiagnostics( ` @service(#{title: "My service"}) @server("https://{region}.example.com", "Regional account endpoint", {region: Region}) @@ -87,8 +97,10 @@ worksFor(supportedVersions, ({ diagnoseOpenApiFor, openApiFor, version: specVers eastUs: 2, } `, + { "openapi-versions": [specVersion] }, ); - deepStrictEqual(res.servers[0].variables.region, { + expectDiagnostics(diagnostics, missingDefaultWarning("region", "westus")); + deepStrictEqual(res.servers?.[0].variables?.region, { default: "westus", enum: ["westus", "eastus"], }); @@ -237,7 +249,7 @@ worksFor(supportedVersions, ({ diagnoseOpenApiFor, openApiFor, version: specVers }); it("set a server with enum properties", async () => { - const res = await openApiFor( + const [res, diagnostics] = await emitOpenApiWithDiagnostics( ` enum Region { westus, eastus } @service(#{title: "My service"}) @@ -246,7 +258,9 @@ worksFor(supportedVersions, ({ diagnoseOpenApiFor, openApiFor, version: specVers }) namespace MyService {} `, + { "openapi-versions": [specVersion] }, ); + expectDiagnostics(diagnostics, missingDefaultWarning("region", "westus")); deepStrictEqual(res.servers, [ { description: "Regional account endpoint", @@ -297,7 +311,7 @@ worksFor(supportedVersions, ({ diagnoseOpenApiFor, openApiFor, version: specVers }); it("set a server with unions type", async () => { - const res = await openApiFor( + const [res, diagnostics] = await emitOpenApiWithDiagnostics( ` enum Region { } @service(#{title: "My service"}) @@ -306,7 +320,9 @@ worksFor(supportedVersions, ({ diagnoseOpenApiFor, openApiFor, version: specVers }) namespace MyService {} `, + { "openapi-versions": [specVersion] }, ); + expectDiagnostics(diagnostics, missingDefaultWarning("region", "westus")); deepStrictEqual(res.servers, [ { description: "Regional account endpoint", @@ -338,15 +354,12 @@ worksFor(supportedVersions, ({ diagnoseOpenApiFor, openApiFor, version: specVers ` @versioned(Versions) @service(#{title: "My service"}) - @server("{endpoint}/{release}/{apiVersion}", "Versioned endpoint", { + @server("{endpoint}/{apiVersion}", "Versioned endpoint", { endpoint: url, - release: Release, apiVersion: Versions, }) namespace MyService { enum Versions { v1: "2024-01-01", v2: "2025-01-01" } - // Same values as Versions, but not the versions enum, so it keeps the first value. - enum Release { previous: "2024-01-01", latest: "2025-01-01" } } `, ["2024-01-01", "2025-01-01"], @@ -354,6 +367,43 @@ worksFor(supportedVersions, ({ diagnoseOpenApiFor, openApiFor, version: specVers ); for (const [version, document] of Object.entries(documents)) { deepStrictEqual(document.servers?.[0].variables, { + endpoint: { default: "" }, + apiVersion: { default: version, enum: ["2024-01-01", "2025-01-01"] }, + }); + } + }); + + it("warns once for a server variable without a default in a versioned service", async () => { + const [{ outputs }, diagnostics] = await TesterWithVersioning.compileAndDiagnose( + ` + @versioned(Versions) + @service(#{title: "My service"}) + @server("{endpoint}/{release}/{apiVersion}", "Versioned endpoint", { + endpoint: url, + release: Release, + apiVersion: Versions, + }) + namespace MyService { + enum Versions { v1: "2024-01-01", v2: "2025-01-01" } + // Same values as Versions, but not the versions enum, so it keeps the first value. + enum Release { previous: "2024-01-01", latest: "2025-01-01" } + } + `, + { + compilerOptions: { + options: { + "@typespec/openapi3": { + "openapi-versions": [specVersion], + "output-file": "{version}.openapi.json", + }, + }, + }, + }, + ); + expectDiagnostics(diagnostics, missingDefaultWarning("release", "2024-01-01")); + for (const version of ["2024-01-01", "2025-01-01"]) { + const document = JSON.parse(outputs[`${version}.openapi.json`]); + deepStrictEqual(document.servers[0].variables, { endpoint: { default: "" }, release: { default: "2024-01-01", enum: ["2024-01-01", "2025-01-01"] }, apiVersion: { default: version, enum: ["2024-01-01", "2025-01-01"] }, From d20dd3124d3f0d84da506607854c52aa5ac7292a Mon Sep 17 00:00:00 2001 From: Yashvardhan Thanvi Date: Wed, 28 Oct 2026 15:46:42 +0530 Subject: [PATCH 3/3] fix(openapi3): warn about a missing server variable default instead of picking one Keep the empty default when a server variable with enum values has no default, and report missing-server-variable-default only for OpenAPI 3.1.0 and later, which require the default to be one of the enum values. --- ...ariable-enum-default-2026-9-19-11-21-11.md | 2 +- .../missing-server-variable-default.md | 8 +- packages/openapi3/src/lib.ts | 2 +- packages/openapi3/src/openapi.ts | 55 +++-------- packages/openapi3/test/servers.test.ts | 98 +++++-------------- 5 files changed, 44 insertions(+), 121 deletions(-) diff --git a/.chronus/changes/fix-openapi3-server-variable-enum-default-2026-9-19-11-21-11.md b/.chronus/changes/fix-openapi3-server-variable-enum-default-2026-9-19-11-21-11.md index 608415cdc79..66fe2932925 100644 --- a/.chronus/changes/fix-openapi3-server-variable-enum-default-2026-9-19-11-21-11.md +++ b/.chronus/changes/fix-openapi3-server-variable-enum-default-2026-9-19-11-21-11.md @@ -4,4 +4,4 @@ packages: - "@typespec/openapi3" --- -Server variables that have an `enum` but no default now use the first `enum` value as their `default` instead of an empty string, since OpenAPI 3.1 and later require the default to be one of the `enum` values. A server variable typed as the service's versions enum uses the version of each emitted document instead. A new `missing-server-variable-default` warning is reported when that first value is used for a variable with more than one possible value. +Report a new `missing-server-variable-default` warning when a server variable that has an `enum` has no default and the document is emitted for OpenAPI 3.1.0 or later, since those versions require the default to be one of the `enum` values. The emitted `default` stays an empty string. diff --git a/packages/openapi3/src/diagnostics/missing-server-variable-default.md b/packages/openapi3/src/diagnostics/missing-server-variable-default.md index 1800a3f41ec..556d6ae5aa0 100644 --- a/packages/openapi3/src/diagnostics/missing-server-variable-default.md +++ b/packages/openapi3/src/diagnostics/missing-server-variable-default.md @@ -1,5 +1,5 @@ -This diagnostic is issued when a variable in the `@server` decorator can take more than one value (an enum or a union of string literals) but has no default. -OpenAPI requires the `default` of a server variable to be one of its `enum` values, so the emitter uses the first value. That value might not be the one you intended. +This diagnostic is issued when a variable in the `@server` decorator has a fixed set of values (an enum, a union of string literals or a string literal) but no default, and the document is emitted for OpenAPI 3.1.0 or later. +Those versions require the `default` of a server variable to be one of its `enum` values. The emitter does not pick one for you, so the variable keeps an empty `default` and the document is not valid. To fix this issue, set a default on the server parameter. @@ -7,11 +7,11 @@ To fix this issue, set a default on the server parameter. ```typespec @server("https://{region}.example.com", "Regional endpoint", { - region: "westus" | "eastus", // No default, so "westus" is used + region: "westus" | "eastus", // No default }) ``` -Set a default to choose the value: +Set a default: ```typespec @server("https://{region}.example.com", "Regional endpoint", { diff --git a/packages/openapi3/src/lib.ts b/packages/openapi3/src/lib.ts index f1d731075ec..a3e3aa637f1 100644 --- a/packages/openapi3/src/lib.ts +++ b/packages/openapi3/src/lib.ts @@ -341,7 +341,7 @@ export const $lib = createTypeSpecLibrary({ severity: "warning", docs: fileRef.fromPackageRoot("src/diagnostics/missing-server-variable-default.md"), messages: { - default: paramMessage`Server variable '${"propName"}' has no default, so '${"value"}', the first of its values, is used. Set a default on the parameter to choose a different one.`, + default: paramMessage`Server variable '${"propName"}' has no default, but OpenAPI ${"openapiVersion"} requires its default to be one of its enum values. Set a default on the parameter.`, }, }, "invalid-format": { diff --git a/packages/openapi3/src/openapi.ts b/packages/openapi3/src/openapi.ts index 1924efeb1bb..82f9883c6f9 100644 --- a/packages/openapi3/src/openapi.ts +++ b/packages/openapi3/src/openapi.ts @@ -137,7 +137,6 @@ import { isBytesKeptRaw, isSharedHttpOperation, } from "./util.js"; -import type { VersioningModule } from "./versioning-module.js"; import { resolveVersioningModule } from "./versioning-module.js"; import type { VisibilityUsageTracker } from "./visibility-usage.js"; import { resolveVisibilityUsage } from "./visibility-usage.js"; @@ -348,7 +347,6 @@ function createOAPIEmitter( let visibilityUsage: VisibilityUsageTracker; let sseModule: SSEModule | undefined; let jsonSchemaModule: JsonSchemaModule | undefined; - let versioningModule: VersioningModule | undefined; // Map model properties that represent shared parameters to their parameter // definition that will go in #/components/parameters. Inlined parameters do not go in @@ -362,13 +360,10 @@ function createOAPIEmitter( // De-dupe the per-endpoint tags that will be added into the #/tags let tagsUsedInOperations: Set; - // Values already warned about for a server parameter with no default, keyed by its declaration. + // Server parameters already warned about for a missing default, keyed by their declaration. // Servers are resolved once per document and each version of a versioned service gets its own // copy of the parameter, so without this the same warning would be reported for every version. - const serverVariablesWarnedForDefault = new Map< - ModelProperty["node"] | ModelProperty, - Set - >(); + const serverVariablesWarnedForDefault = new Set(); const typeNameOptions: TypeNameOptions = { // shorten type names by removing TypeSpec and service namespace @@ -510,7 +505,7 @@ function createOAPIEmitter( const servers = getServers(program, service.type); if (servers) { - root.servers = resolveServers(servers, version); + root.servers = resolveServers(servers); } attachExtensions(program, service.type, root); @@ -557,34 +552,22 @@ function createOAPIEmitter( return isValid; } - /** Whether `type` is the enum passed to `@versioned` on the current service. */ - function isServiceVersionsEnum(type: Type): boolean { - const versionMap = versioningModule?.getVersion(program, currentService.type); - return versionMap?.getVersions().some((v) => v.enumMember.enum === type) ?? false; - } - - function reportMissingServerVariableDefault(prop: ModelProperty, value: string) { - // Template instances share a declaration but can have different values, so only skip a - // warning that was already reported for the same declaration and value. + function reportMissingServerVariableDefault(prop: ModelProperty) { const key = prop.node ?? prop; - let warnedValues = serverVariablesWarnedForDefault.get(key); - if (warnedValues === undefined) { - warnedValues = new Set(); - serverVariablesWarnedForDefault.set(key, warnedValues); - } else if (warnedValues.has(value)) { + if (serverVariablesWarnedForDefault.has(key)) { return; } - warnedValues.add(value); + serverVariablesWarnedForDefault.add(key); diagnostics.add( createDiagnostic({ code: "missing-server-variable-default", - format: { propName: prop.name, value }, + format: { propName: prop.name, openapiVersion: specVersion }, target: prop, }), ); } - function resolveServers(servers: HttpServer[], version?: string): OpenAPI3Server[] { + function resolveServers(servers: HttpServer[]): OpenAPI3Server[] { return servers.map((server) => { const variables: Record = {}; for (const [name, prop] of server.parameters) { @@ -606,22 +589,10 @@ function createOAPIEmitter( } else if (prop.type.kind === "String") { variable.enum = [prop.type.value]; } - // OpenAPI requires `default` to be one of the `enum` values. Use the version being - // emitted for the versions enum, and the first value otherwise. - if (!prop.defaultValue && variable.enum?.length) { - if ( - version !== undefined && - variable.enum.includes(version) && - isServiceVersionsEnum(prop.type) - ) { - variable.default = version; - } else { - variable.default = variable.enum[0]; - // With more than one value the first one is only a guess, so tell the author. - if (variable.enum.length > 1) { - reportMissingServerVariableDefault(prop, variable.default); - } - } + // OpenAPI 3.1 and later require `default` to be one of the `enum` values (3.0 only says + // it should be). Picking one could choose the wrong value, so ask the author to set it. + if (!prop.defaultValue && variable.enum?.length && specVersion !== "3.0.0") { + reportMissingServerVariableDefault(prop); } attachExtensions(program, prop, variable); variables[name] = variable; @@ -635,7 +606,7 @@ function createOAPIEmitter( } async function getOpenAPI(): Promise { - versioningModule = await resolveVersioningModule(); + const versioningModule = await resolveVersioningModule(); const serviceRecords: OpenAPI3ServiceRecord[] = []; const services = listServices(program); if (services.length === 0) { diff --git a/packages/openapi3/test/servers.test.ts b/packages/openapi3/test/servers.test.ts index 09f42c65f5a..c581fa96782 100644 --- a/packages/openapi3/test/servers.test.ts +++ b/packages/openapi3/test/servers.test.ts @@ -1,19 +1,21 @@ import { expectDiagnostics } from "@typespec/compiler/testing"; import { deepStrictEqual } from "assert"; import { it } from "vitest"; -import { - emitOpenApiWithDiagnostics, - openApiForVersions, - TesterWithVersioning, -} from "./test-host.js"; +import { emitOpenApiWithDiagnostics, TesterWithVersioning } from "./test-host.js"; import { supportedVersions, worksFor } from "./works-for.js"; worksFor(supportedVersions, ({ diagnoseOpenApiFor, openApiFor, version: specVersion }) => { - const missingDefaultWarning = (name: string, value: string) => ({ - code: "@typespec/openapi3/missing-server-variable-default", - severity: "warning" as const, - message: `Server variable '${name}' has no default, so '${value}', the first of its values, is used. Set a default on the parameter to choose a different one.`, - }); + // OpenAPI 3.0 only says that a server variable default should be one of its enum values. + const missingDefaultWarnings = (name: string) => + specVersion === "3.0.0" + ? [] + : [ + { + code: "@typespec/openapi3/missing-server-variable-default", + severity: "warning" as const, + message: `Server variable '${name}' has no default, but OpenAPI ${specVersion} requires its default to be one of its enum values. Set a default on the parameter.`, + }, + ]; it("set a basic server(url)", async () => { const res = await openApiFor( @@ -99,32 +101,8 @@ worksFor(supportedVersions, ({ diagnoseOpenApiFor, openApiFor, version: specVers `, { "openapi-versions": [specVersion] }, ); - expectDiagnostics(diagnostics, missingDefaultWarning("region", "westus")); - deepStrictEqual(res.servers?.[0].variables?.region, { - default: "westus", - enum: ["westus", "eastus"], - }); - }); - - it("keeps an explicit default for an enum whose members are encoded as strings", async () => { - const res = await openApiFor( - ` - @service(#{title: "My service"}) - @server("https://{region}.example.com", "Regional account endpoint", {region?: Region = Region.eastUs}) - namespace MyService {} - - enum Region { - @encodedName("application/json", "westus") - westUs: 1, - @encodedName("application/json", "eastus") - eastUs: 2, - } - `, - ); - deepStrictEqual(res.servers[0].variables.region, { - default: "eastus", - enum: ["westus", "eastus"], - }); + expectDiagnostics(diagnostics, missingDefaultWarnings("region")); + deepStrictEqual(res.servers?.[0].variables?.region?.enum, ["westus", "eastus"]); }); it("emit diagnostic when a numeric enum member is left unencoded", async () => { @@ -260,13 +238,13 @@ worksFor(supportedVersions, ({ diagnoseOpenApiFor, openApiFor, version: specVers `, { "openapi-versions": [specVersion] }, ); - expectDiagnostics(diagnostics, missingDefaultWarning("region", "westus")); + expectDiagnostics(diagnostics, missingDefaultWarnings("region")); deepStrictEqual(res.servers, [ { description: "Regional account endpoint", url: "https://{region}.example.com", variables: { - region: { default: "westus", enum: ["westus", "eastus"] }, + region: { default: "", enum: ["westus", "eastus"] }, }, }, ]); @@ -289,7 +267,7 @@ worksFor(supportedVersions, ({ diagnoseOpenApiFor, openApiFor, version: specVers }); it("set a server with string literal", async () => { - const res = await openApiFor( + const [res, diagnostics] = await emitOpenApiWithDiagnostics( ` enum Region { } @service(#{title: "My service"}) @@ -298,13 +276,15 @@ worksFor(supportedVersions, ({ diagnoseOpenApiFor, openApiFor, version: specVers }) namespace MyService {} `, + { "openapi-versions": [specVersion] }, ); + expectDiagnostics(diagnostics, missingDefaultWarnings("region")); deepStrictEqual(res.servers, [ { description: "Regional account endpoint", url: "https://{region}.example.com", variables: { - region: { default: "westus", enum: ["westus"] }, + region: { default: "", enum: ["westus"] }, }, }, ]); @@ -322,13 +302,13 @@ worksFor(supportedVersions, ({ diagnoseOpenApiFor, openApiFor, version: specVers `, { "openapi-versions": [specVersion] }, ); - expectDiagnostics(diagnostics, missingDefaultWarning("region", "westus")); + expectDiagnostics(diagnostics, missingDefaultWarnings("region")); deepStrictEqual(res.servers, [ { description: "Regional account endpoint", url: "https://{region}.example.com", variables: { - region: { default: "westus", enum: ["westus", "eastus"] }, + region: { default: "", enum: ["westus", "eastus"] }, }, }, ]); @@ -349,44 +329,17 @@ worksFor(supportedVersions, ({ diagnoseOpenApiFor, openApiFor, version: specVers }); }); - it("set a server with the versions enum to the version of each document", async () => { - const documents = await openApiForVersions( - ` - @versioned(Versions) - @service(#{title: "My service"}) - @server("{endpoint}/{apiVersion}", "Versioned endpoint", { - endpoint: url, - apiVersion: Versions, - }) - namespace MyService { - enum Versions { v1: "2024-01-01", v2: "2025-01-01" } - } - `, - ["2024-01-01", "2025-01-01"], - { "openapi-versions": [specVersion] }, - ); - for (const [version, document] of Object.entries(documents)) { - deepStrictEqual(document.servers?.[0].variables, { - endpoint: { default: "" }, - apiVersion: { default: version, enum: ["2024-01-01", "2025-01-01"] }, - }); - } - }); - it("warns once for a server variable without a default in a versioned service", async () => { const [{ outputs }, diagnostics] = await TesterWithVersioning.compileAndDiagnose( ` @versioned(Versions) @service(#{title: "My service"}) - @server("{endpoint}/{release}/{apiVersion}", "Versioned endpoint", { + @server("{endpoint}/{apiVersion}", "Versioned endpoint", { endpoint: url, - release: Release, apiVersion: Versions, }) namespace MyService { enum Versions { v1: "2024-01-01", v2: "2025-01-01" } - // Same values as Versions, but not the versions enum, so it keeps the first value. - enum Release { previous: "2024-01-01", latest: "2025-01-01" } } `, { @@ -400,13 +353,12 @@ worksFor(supportedVersions, ({ diagnoseOpenApiFor, openApiFor, version: specVers }, }, ); - expectDiagnostics(diagnostics, missingDefaultWarning("release", "2024-01-01")); + expectDiagnostics(diagnostics, missingDefaultWarnings("apiVersion")); for (const version of ["2024-01-01", "2025-01-01"]) { const document = JSON.parse(outputs[`${version}.openapi.json`]); deepStrictEqual(document.servers[0].variables, { endpoint: { default: "" }, - release: { default: "2024-01-01", enum: ["2024-01-01", "2025-01-01"] }, - apiVersion: { default: version, enum: ["2024-01-01", "2025-01-01"] }, + apiVersion: { default: "", enum: ["2024-01-01", "2025-01-01"] }, }); } });