Repository navigation
fix(openapi3): use the first enum value as the server variable default - #12302
Yashvardhan Thanvi (Thanatos9404) wants to merge 2 commits into
Conversation
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.
microsoft-github-policy-service
Bot
added
the
emitter:openapi3
commit: |
|
All changed packages have been documented.
Show changes
|
There was a problem hiding this comment.
actually I think this is doing an unexpected behavior here, we should emit a warning to let the author know we set something that is probably not right
There was a problem hiding this comment.
Good call. It now reports a missing-server-variable-default warning when it falls back to the first value, so the author knows to set a default (207198d). It doesn't warn when the variable is the service's versions enum, since each document then gets its own version rather than a guess, or when there is only one possible value, and in a versioned service the warning shows once rather than once per version. Happy to warn in those cases too if you'd prefer.
…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.
Fixes #6024
A server variable typed as an enum, a union of string literals or a single string literal gets an
enumin the emitted document, but without a TypeSpec default itsdefaultwas always"". OpenAPI 3.1 and 3.2 saydefaultMUST be one of theenumvalues (3.0 says SHOULD), so those documents were invalid.In
resolveServers, when there is no default and anenumwas computed, the firstenumvalue is now used, for all OpenAPI versions. An explicit default is kept, and a plainstringvariable still gets"". When the first value is used for a variable with more than one possible value, a newmissing-server-variable-defaultwarning tells the author to set a default.One exception: a variable typed as the service's
@versionedenum (likeapiVersion: Versions) defaults to the version of the document being emitted, so versioned documents don't all default to the oldest version. For this,initializeEmitterpasses the version toresolveServers, using the versioning module the emitter already loads.Testing: three existing tests in
servers.test.tsthat pinneddefault: ""now expect the first enum value, and new tests cover explicit defaults and the versioned case. On main 15 of the 57 tests in that file fail; with this change all pass.