updates openapi @extension to support value types, and removes starts with x- extension name constraint

[chrisradek]

Resolves #6076
 
This PR makes a few changes to the @typespec/openapi @extension decorator to align it closer to the @typespec/json-schema @extension decorator.

@extension is updated in 3 ways:

1. The x- prefix is no longer required for the extension name.
2. Value kinds are now supported and will be inserted in the Open API doc as raw values.
3. Passing in types (e.g. typeof "foo", model expressions, tuple types) retains current behavior but also triggers a deprecation warning.

What's with the deprecation warning?

Prior to this PR, passed in types would be converted to JSON values (or emit an error if they couldn't be converted).
So the following TypeSpec

@OpenAPI.extension("x-foo", { foo: true })
model Foo {}

would emit the following OpenAPI:

Foo:
  type: object
  x-foo:
    foo: true

However, in a follow-up release, passing in the type { foo: true } will cause an OpenAPI schema to be emitted instead:

Foo:
  type: object
  x-foo:
    type: object
    required:
      - foo
    properties:
      foo:
        type: boolean
        enum:
          - true

To get back to the current behavior, #{ foo: true } should be passed instead.

The deprecation warning gives users at least 1 release to be aware of the change and update their code accordingly.

Follow-ups

• typespec-azure PR: updates @OpenAPI.extension usage to use value kinds Azure/typespec-azure#2236
• Update azure-specs repo to use values

[azure-sdk]

All changed packages have been documented.

• ✅ @typespec/openapi

Show changes

@typespec/openapi - feature ✏️

Updates the @extension decorator with 3 changes:,> ,> 1. Removes the extension name starts with x- constraint.,> 1. Adds support for passing in values to emit raw data.,> 1. Adds a deprecation warning for passing in types. Passed in types will emit Open API schemas in a future release.,> ,> Scalar literals (e.g. string, boolean, number values) are automatically treated as values.,> Model or tuple expression usage needs to be converted to values to retain current behavior in future releases.,> ,> diff lang="tsp",> -@extension("x-obj", { foo: true }),> +@extension("x-obj", #{ foo: true }),> -@extension("x-tuple", [ "foo" ]),> +@extension("x-tuple", #[ "foo" ]),> model Foo {},>

[azure-sdk]

You can try these changes here

🛝 Playground	🌐 Website	📚 Next docs	🛝 VSCode Extension

[timotheeguerin]

I assume this will need quite the patch in the spec repos

[chrisradek]

I assume this will need quite the patch in the spec repos

Yes - I'll hold off on merging until the typespec-azure/azure specs PRs are ready/approved.