Add security scheme descriptions to Azure Core data-plane playground sample

[Copilot]

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

/** 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;

[microsoft-github-policy-service]

Hi @@copilot. Your PR has had no update for 14 days and it is marked as a stale PR. If it is not updated within 14 days, the PR will automatically be closed. If you want to refresh the PR, please remove the stale label.

[github-actions]

⚡ Benchmark Results

⚠️ 7 metric(s) regressed above the +5% threshold:

Metric	Baseline	Current	Change
↳ linter/@azure-tools/typespec-azure-core/no-header-explode	🟡 18.2ms	🟡 19.7ms	+8.6% 🔴
↳ linter/@azure-tools/typespec-azure-core/no-response-body	🔴 23.0ms	🔴 24.2ms	+5.3% 🔴
↳ linter/@azure-tools/typespec-azure-core/no-route-parameter-name-mismatch	🟢 4.6ms	🟢 5.7ms	+22.2% 🔴
↳ linter/@azure-tools/typespec-azure-core/response-schema-problem	🔴 21.4ms	🔴 23.1ms	+7.9% 🔴
↳ emit/@typespec/http-client-js	🔴 1.11s	🔴 1.19s	+7.1% 🔴
↳ emit/@typespec/openapi3	🟢 139.5ms	🟢 148.6ms	+6.5% 🔴
↳ emit/@typespec/openapi3/compute	🟢 121.4ms	🟢 130.6ms	+7.6% 🔴

Full details – comparing fc57754 vs baseline 40aa6fc

Metric	Baseline	Current	Change
total	🔴 587.5ms	🔴 610.9ms	+4.0%
loader	🟢 155.8ms	🟢 148.0ms	-5.0% 🟢
resolver	🟢 18.5ms	🟢 17.0ms	-7.9% 🟢
checker	🟢 181.7ms	🟢 189.4ms	+4.3%
validation	🟢 41.5ms	🟢 42.4ms	+2.4%
↳ validation/@azure-tools/typespec-azure-core	🟢 5.9ms	🟢 6.6ms	+12.3%
↳ validation/@typespec/http	🟢 5.0ms	🟢 5.2ms	+4.2%
↳ validation/@typespec/rest	🟢 0.6ms	🟢 0.6ms	+8.3%
↳ validation/@typespec/versioning	🔴 28.0ms	🔴 28.0ms	+0.3%
↳ validation/compiler	🟢 1.5ms	🟢 1.4ms	-3.5%
linter	🟢 131.7ms	🟢 137.4ms	+4.4%
↳ linter/@azure-tools/typespec-azure-core/auth-required	🟢 0.0ms	🟢 0.0ms	+3.4%
↳ linter/@azure-tools/typespec-azure-core/bad-record-type	🟢 0.2ms	🟢 0.3ms	+16.7%
↳ linter/@azure-tools/typespec-azure-core/byos	🟢 5.9ms	🟢 5.9ms	+0.8%
↳ linter/@azure-tools/typespec-azure-core/casing-style	🟢 0.6ms	🟢 0.6ms	+3.5%
↳ linter/@azure-tools/typespec-azure-core/composition-over-inheritance	🟢 0.1ms	🟢 0.1ms	-12.0%
↳ linter/@azure-tools/typespec-azure-core/documentation-required	🟢 0.8ms	🟢 1.0ms	+18.2%
↳ linter/@azure-tools/typespec-azure-core/friendly-name	🟢 0.6ms	🟢 0.7ms	+7.1%
↳ linter/@azure-tools/typespec-azure-core/key-visibility-required	🟢 0.2ms	🟢 0.2ms	+2.7%
↳ linter/@azure-tools/typespec-azure-core/known-encoding	🟢 0.3ms	🟢 0.3ms	-3.7%
↳ linter/@azure-tools/typespec-azure-core/long-running-polling-operation-required	🟢 0.3ms	🟢 0.3ms	+3.4%
↳ linter/@azure-tools/typespec-azure-core/no-case-mismatch	🟢 0.2ms	🟢 0.2ms	-4.1%
↳ linter/@azure-tools/typespec-azure-core/no-closed-literal-union	🟢 0.2ms	🟢 0.3ms	+6.0%
↳ linter/@azure-tools/typespec-azure-core/no-enum	🟢 0.1ms	🟢 0.0ms	-15.0%
↳ linter/@azure-tools/typespec-azure-core/no-error-status-codes	🟢 0.1ms	🟢 0.1ms	+2.5%
↳ linter/@azure-tools/typespec-azure-core/no-explicit-routes-resource-ops	🟢 0.1ms	🟢 0.1ms	+10.0%
↳ linter/@azure-tools/typespec-azure-core/no-format	🟢 0.6ms	🟢 0.6ms	+13.4%
↳ linter/@azure-tools/typespec-azure-core/no-generic-numeric	🟢 0.4ms	🟢 0.4ms	-9.0%
↳ linter/@azure-tools/typespec-azure-core/no-header-explode	🟡 18.2ms	🟡 19.7ms	+8.6% 🔴
↳ linter/@azure-tools/typespec-azure-core/no-legacy-usage	🟢 1.1ms	🟢 1.1ms	-1.7%
↳ linter/@azure-tools/typespec-azure-core/no-multiple-discriminator	🟢 0.1ms	🟢 0.1ms	-0.7%
↳ linter/@azure-tools/typespec-azure-core/no-nullable	🟢 0.2ms	🟢 0.3ms	+6.0%
↳ linter/@azure-tools/typespec-azure-core/no-offsetdatetime	🟢 1.2ms	🟢 1.2ms	-2.3%
↳ linter/@azure-tools/typespec-azure-core/no-openapi	🟢 2.0ms	🟢 2.1ms	+4.1%
↳ linter/@azure-tools/typespec-azure-core/no-private-usage	🟢 1.9ms	🟢 2.0ms	+6.8%
↳ linter/@azure-tools/typespec-azure-core/no-query-explode	🟡 19.4ms	🟡 19.8ms	+2.2%
↳ linter/@azure-tools/typespec-azure-core/no-response-body	🔴 23.0ms	🔴 24.2ms	+5.3% 🔴
↳ linter/@azure-tools/typespec-azure-core/no-rest-library-interfaces	🟢 0.0ms	🟢 0.0ms	+1.1%
↳ linter/@azure-tools/typespec-azure-core/no-route-parameter-name-mismatch	🟢 4.6ms	🟢 5.7ms	+22.2% 🔴
↳ linter/@azure-tools/typespec-azure-core/no-rpc-path-params	🟢 0.2ms	🟢 0.2ms	+7.8%
↳ linter/@azure-tools/typespec-azure-core/no-string-discriminator	🟢 0.0ms	🟢 0.0ms	-6.3%
↳ linter/@azure-tools/typespec-azure-core/no-unknown	🟢 0.2ms	🟢 0.2ms	+23.8%
↳ linter/@azure-tools/typespec-azure-core/no-unnamed-union	🟢 0.3ms	🟢 0.4ms	+25.0%
↳ linter/@azure-tools/typespec-azure-core/operation-missing-api-version	🟢 0.2ms	🟢 0.2ms	+12.6%
↳ linter/@azure-tools/typespec-azure-core/request-body-problem	🟢 0.3ms	🟢 0.3ms	-2.8%
↳ linter/@azure-tools/typespec-azure-core/require-versioned	🟢 0.0ms	🟢 0.0ms	+11.7%
↳ linter/@azure-tools/typespec-azure-core/response-schema-problem	🔴 21.4ms	🔴 23.1ms	+7.9% 🔴
↳ linter/@azure-tools/typespec-azure-core/rpc-operation-request-body	🟢 0.3ms	🟢 0.4ms	+44.0%
↳ linter/@azure-tools/typespec-azure-core/spread-discriminated-model	🟢 0.3ms	🟢 0.3ms	+11.9%
↳ linter/@azure-tools/typespec-azure-core/use-standard-names	🟢 4.7ms	🟢 5.6ms	+18.8%
↳ linter/@azure-tools/typespec-azure-core/use-standard-operations	🟢 0.1ms	🟢 0.1ms	+5.9%
↳ linter/@azure-tools/typespec-azure-resource-manager/arm-agent-base-type-child-resources	🟢 3.9ms	🟢 4.0ms	+0.9%
↳ linter/@azure-tools/typespec-azure-resource-manager/arm-agent-base-type-lifecycle-operations	🟢 0.0ms	🟢 0.0ms	+16.8%
↳ linter/@azure-tools/typespec-azure-resource-manager/arm-common-types-version	🟢 3.7ms	🟢 4.0ms	+6.6%
↳ linter/@azure-tools/typespec-azure-resource-manager/arm-custom-resource-no-key	🟢 0.1ms	🟢 0.1ms	-8.5%
↳ linter/@azure-tools/typespec-azure-resource-manager/arm-custom-resource-usage-discourage	🟢 0.1ms	🟢 0.1ms	+5.0%
↳ linter/@azure-tools/typespec-azure-resource-manager/arm-delete-operation-response-codes	🟢 1.0ms	🟢 1.0ms	+1.9%
↳ linter/@azure-tools/typespec-azure-resource-manager/arm-no-path-casing-conflicts	🟢 4.1ms	🟢 4.2ms	+2.3%
↳ linter/@azure-tools/typespec-azure-resource-manager/arm-no-record	🟢 0.4ms	🟢 0.4ms	+7.3%
↳ linter/@azure-tools/typespec-azure-resource-manager/arm-post-operation-response-codes	🟢 0.4ms	🟢 0.4ms	-3.6%
↳ linter/@azure-tools/typespec-azure-resource-manager/arm-put-operation-response-codes	🟢 0.0ms	🟢 0.0ms	+21.6%
↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-action-no-segment	🟢 0.2ms	🟢 0.2ms	+19.2%
↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-duplicate-property	🟢 0.1ms	🟢 0.1ms	-8.7%
↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-interface-requires-decorator	🟢 0.0ms	🟢 0.0ms	+2.3%
↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-invalid-action-verb	🟢 0.1ms	🟢 0.1ms	+5.9%
↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-invalid-envelope-property	🟢 0.1ms	🟢 0.1ms	-4.1%
↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-invalid-version-format	🟢 0.0ms	🟢 0.0ms	+6.6%
↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-key-invalid-chars	🟢 0.2ms	🟢 0.2ms	-0.3%
↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-name-pattern	🟢 0.0ms	🟢 0.0ms	-8.2%
↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-operation	🟢 0.2ms	🟢 0.2ms	+4.3%
↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-operation-response	🟢 4.3ms	🟢 4.5ms	+5.9%
↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-patch	🟢 0.3ms	🟢 0.3ms	+4.5%
↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-path-segment-invalid-chars	🟢 0.2ms	🟢 0.2ms	+8.8%
↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-provisioning-state	🟢 0.1ms	🟢 0.1ms	+4.2%
↳ linter/@azure-tools/typespec-azure-resource-manager/beyond-nesting-levels	🟢 0.1ms	🟢 0.1ms	-3.9%
↳ linter/@azure-tools/typespec-azure-resource-manager/empty-updateable-properties	🟢 0.2ms	🟢 0.1ms	-12.7%
↳ linter/@azure-tools/typespec-azure-resource-manager/improper-subscription-list-operation	🟢 0.0ms	🟢 0.0ms	-1.1%
↳ linter/@azure-tools/typespec-azure-resource-manager/lro-location-header	🟡 12.8ms	🟡 12.3ms	-4.3%
↳ linter/@azure-tools/typespec-azure-resource-manager/missing-operations-endpoint	🟢 0.0ms	🟢 0.0ms	+5.8%
↳ linter/@azure-tools/typespec-azure-resource-manager/missing-x-ms-identifiers	🟢 0.3ms	🟢 0.3ms	+5.7%
↳ linter/@azure-tools/typespec-azure-resource-manager/no-empty-model	🟢 0.1ms	🟢 0.1ms	+1.6%
↳ linter/@azure-tools/typespec-azure-resource-manager/no-override-props	🟢 0.1ms	🟢 0.1ms	+0.5%
↳ linter/@azure-tools/typespec-azure-resource-manager/no-resource-delete-operation	🟢 0.2ms	🟢 0.2ms	-3.4%
↳ linter/@azure-tools/typespec-azure-resource-manager/no-response-body	🔴 22.2ms	🔴 22.0ms	-0.7%
↳ linter/@azure-tools/typespec-azure-resource-manager/patch-envelope	🟢 0.1ms	🟢 0.1ms	-6.5%
↳ linter/@azure-tools/typespec-azure-resource-manager/resource-name	🟢 0.1ms	🟢 0.1ms	-4.7%
↳ linter/@azure-tools/typespec-azure-resource-manager/secret-prop	🟢 2.4ms	🟢 2.4ms	-2.8%
↳ linter/@azure-tools/typespec-azure-resource-manager/unsupported-type	🟢 0.3ms	🟢 0.4ms	+8.2%
↳ linter/@azure-tools/typespec-azure-resource-manager/version-progression	🟢 0.0ms	🟢 0.0ms	-3.8%
↳ linter/@azure-tools/typespec-client-generator-core/property-name-conflict	🟢 1.0ms	🟢 1.1ms	+5.9%
↳ linter/@azure-tools/typespec-client-generator-core/require-client-suffix	🟢 0.2ms	🟢 0.2ms	+5.2%
emit	🔴 5.66s	🔴 5.71s	+0.9%
↳ emit/@azure-tools/typespec-autorest	🟢 156.3ms	🟢 163.0ms	+4.3%
↳ emit/@azure-tools/typespec-python	🔴 4.16s	🔴 4.13s	-0.7%
↳ emit/@typespec/http-client-js	🔴 1.11s	🔴 1.19s	+7.1% 🔴
↳ emit/@typespec/openapi3	🟢 139.5ms	🟢 148.6ms	+6.5% 🔴
↳ emit/@typespec/openapi3/compute	🟢 121.4ms	🟢 130.6ms	+7.6% 🔴
↳ emit/@typespec/openapi3/write	🟢 18.3ms	🟢 18.0ms	-1.6%

Averaged across 3 specs (azure-arm-resource-manager, azure-core-dataplane, azure-full).
Threshold: changes > ±5% are highlighted.
🟢 Fast · 🟡 Moderate (stages >200ms, rules >10ms) · 🔴 Slow (stages >400ms, rules >20ms)

[timotheeguerin]

@copilot regnerate the sample and format

[Copilot]

@copilot regnerate the sample and format

Done in 9986be3. I regenerated the widget-manager sample snapshots and formatted the updated output.

[timotheeguerin]

@copilot why are those auth models still included in the output, didn't we fix that in openapi and autorest emitter?

[Copilot]

I re-checked this on the current branch/toolchain. If we keep the named auth models (model ... is ApiKeyAuth/OAuth2Auth) to carry doc comments, those names are still what gets emitted in securitySchemes/securityDefinitions. If I switch to aliases/inline auth, the emitted names collapse back to ApiKeyAuth/OAuth2Auth, but the auth description fields disappear. So with what’s currently pinned here, we can have either custom auth descriptions or no custom auth-model names, but not both.

[timotheeguerin]

@copilot PR #4549 should have omitted those models what is that not the case, what is different here? seems like we have a bug

[Copilot]

@copilot regnerate the sample and format

Re-ran widget-manager regeneration and formatting. The current update is in 722a4df.