Add security scheme descriptions to Azure Core data-plane playground sample (#4547)

The Azure Core Data Plane playground sample emitted auth schemes without
`description`, so generated REST docs did not show guidance text for API
key/OAuth2 authentication. This PR updates the sample to model and emit
explicit security scheme descriptions.

- **Problem summary**
- Playground users had no example of how to attach descriptions to
security schemes in TypeSpec Azure data-plane services.
- Generated OpenAPI `securityDefinitions`/`securitySchemes` for the
sample lacked descriptive auth text.

- **Sample update (source)**
  - Updated `packages/samples/specs/data-plane/widget-manager/main.tsp`.
- Replaced inline auth types with named auth models and attached doc
comments (`/** ... */`) to each.
- Updated `@useAuth(...)` to reference those named models so auth docs
propagate into emitted OpenAPI.

- **Snapshot/output update**
  - Regenerated widget-manager sample outputs:
    - `@azure-tools/typespec-autorest/.../openapi.json`
    - `@typespec/openapi3/openapi.2022-08-31.yaml`
- Both now include auth scheme `description` fields for API key and
OAuth2 entries.

- **Example**
```tsp
/** Authenticate requests with an API key in the X-Key header. */
model WidgetManagerApiKeyAuth is ApiKeyAuth<ApiKeyLocation.header, "X-Key">;

/** Authenticate requests with OAuth2 using the widget service scope. */
model WidgetManagerOauth2Auth is OAuth2Auth<[
  {
    type: OAuth2FlowType.implicit,
    authorizationUrl: "https://login.contoso.com/common/oauth2/v2.0/authorize",
    scopes: ["https://widget.contoso.com/.default"],
  }
]>;

@useAuth(WidgetManagerApiKeyAuth | WidgetManagerOauth2Auth)
namespace Contoso.WidgetManager;
```

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>
Co-authored-by: Timothee Guerin <tiguerin@microsoft.com>

Author: Copilot

packages/samples/specs/data-plane/widget-manager/main.tsp

@@ -11,9 +11,22 @@ using Azure.Core.Traits;
 
 @service(#{ title: "Contoso Widget Manager" })
 @versioned(Contoso.WidgetManager.Versions)
-@useAuth(ApiKeyAuth<ApiKeyLocation.header, "X-Key">)
+@useAuth(WidgetManagerApiKeyAuth | WidgetManagerOauth2Auth)
 namespace Contoso.WidgetManager;
 
+/** Authenticate requests with an API key in the X-Key header. */
+model WidgetManagerApiKeyAuth is ApiKeyAuth<ApiKeyLocation.header, "X-Key">;
+
+/** Authenticate requests with OAuth2 using the widget service scope. */
+model WidgetManagerOauth2Auth
+  is OAuth2Auth<[
+    {
+      type: OAuth2FlowType.implicit;
+      authorizationUrl: "https://login.contoso.com/common/oauth2/v2.0/authorize";
+      scopes: ["https://widget.contoso.com/.default"];
+    }
+  ]>;
+
 @doc("The Contoso Widget Manager service version.")
 enum Versions {
   @doc("Version 2022-08-31")

packages/samples/test/output/azure/core/data-plane/widget-manager/@azure-tools/typespec-autorest/2022-08-31/openapi.json

@@ -20,14 +20,29 @@
   ],
   "security": [
     {
-      "ApiKeyAuth": []
+      "WidgetManagerApiKeyAuth": []
+    },
+    {
+      "WidgetManagerOauth2Auth": [
+        "https://widget.contoso.com/.default"
+      ]
     }
   ],
   "securityDefinitions": {
-    "ApiKeyAuth": {
+    "WidgetManagerApiKeyAuth": {
       "type": "apiKey",
+      "description": "Authenticate requests with an API key in the X-Key header.",
       "name": "X-Key",
       "in": "header"
+    },
+    "WidgetManagerOauth2Auth": {
+      "type": "oauth2",
+      "description": "Authenticate requests with OAuth2 using the widget service scope.",
+      "flow": "implicit",
+      "authorizationUrl": "https://login.contoso.com/common/oauth2/v2.0/authorize",
+      "scopes": {
+        "https://widget.contoso.com/.default": ""
+      }
     }
   },
   "tags": [],

packages/samples/test/output/azure/core/data-plane/widget-manager/@typespec/openapi3/openapi.2022-08-31.yaml

@@ -1271,7 +1271,9 @@ paths:
             schema:
               $ref: '#/components/schemas/WidgetRepairRequest'
 security:
-  - ApiKeyAuth: []
+  - WidgetManagerApiKeyAuth: []
+  - WidgetManagerOauth2Auth:
+      - https://widget.contoso.com/.default
 components:
   parameters:
     Azure.Core.ClientRequestIdHeader:
@@ -1684,7 +1686,16 @@ components:
             - SentToManufacturer
       description: The repair state of a widget.
   securitySchemes:
-    ApiKeyAuth:
+    WidgetManagerApiKeyAuth:
       type: apiKey
       in: header
       name: X-Key
+      description: Authenticate requests with an API key in the X-Key header.
+    WidgetManagerOauth2Auth:
+      type: oauth2
+      flows:
+        implicit:
+          authorizationUrl: https://login.contoso.com/common/oauth2/v2.0/authorize
+          scopes:
+            https://widget.contoso.com/.default: ''
+      description: Authenticate requests with OAuth2 using the widget service scope.