Skip to content

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

Open
Copilot wants to merge 7 commits into
mainfrom
copilot/bugfix-security-scheme-descriptions
Open

Add security scheme descriptions to Azure Core data-plane playground sample#4547
Copilot wants to merge 7 commits into
mainfrom
copilot/bugfix-security-scheme-descriptions

Conversation

Copilot AI commented Jun 3, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

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;

Copilot AI linked an issue Jun 3, 2026 that may be closed by this pull request
[Bug]: Data plane sample in TypeSpec Azure playground should have descriptions on security schemes #2532
Open
4 tasks
@timotheeguerin
Add auth scheme descriptions to data-plane widget-manager sample
236ecf0 
Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>
Copilot AI changed the title [WIP] Fix data plane sample to include descriptions on security schemes Add security scheme descriptions to Azure Core data-plane playground sample Jun 3, 2026
Copilot AI requested a review from timotheeguerin June 3, 2026 16:37
timotheeguerin
timotheeguerin reviewed Jun 3, 2026
View reviewed changes
Comment thread packages/samples/specs/data-plane/widget-manager/main.tsp Outdated
@timotheeguerin
Use doc comments for widget-manager auth scheme descriptions
6de4332 
Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>
@microsoft-github-policy-service microsoft-github-policy-service Bot added the stale Mark a PR that hasn't been recently updated and will be closed. label Jun 18, 2026
@microsoft-github-policy-service

microsoft-github-policy-service Bot commented Jun 18, 2026

Copy link
Copy Markdown

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

github-actions Bot commented Jun 18, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

⚡ Benchmark Results

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

Metric Baseline Current Change
total 🔴 666.2ms 🔴 714.9ms +7.3% 🔴
loader 🟢 185.9ms 🟡 202.1ms +8.7% 🔴
checker 🟢 195.1ms 🟡 218.2ms +11.8% 🔴
 ↳ validation/@typespec/http 🟢 5.5ms 🟢 6.6ms +19.7% 🔴
linter 🟢 142.3ms 🟢 156.4ms +9.9% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/no-header-explode 🔴 20.3ms 🔴 22.6ms +11.4% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/no-query-explode 🔴 20.2ms 🔴 23.4ms +16.0% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/no-response-body 🔴 26.4ms 🔴 28.7ms +8.6% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/response-schema-problem 🔴 22.8ms 🔴 26.3ms +15.5% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/lro-location-header 🟡 13.5ms 🟡 14.9ms +10.9% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/no-response-body 🔴 22.2ms 🔴 25.0ms +12.9% 🔴
emit 🔴 6.07s 🔴 6.44s +6.1% 🔴
 ↳ emit/@azure-tools/typespec-autorest 🟢 171.1ms 🟢 185.1ms +8.2% 🔴
 ↳ emit/@azure-tools/typespec-python 🔴 4.36s 🔴 4.74s +8.8% 🔴
 ↳ emit/@typespec/openapi3 🟢 155.2ms 🟢 166.4ms +7.2% 🔴
 ↳ emit/@typespec/openapi3/compute 🟢 136.3ms 🟢 145.5ms +6.8% 🔴
 ↳ emit/@typespec/openapi3/write 🟢 18.9ms 🟢 20.3ms +7.6% 🔴
Full details – comparing b7046ce vs baseline 98ed2f0
Metric Baseline Current Change
total 🔴 666.2ms 🔴 714.9ms +7.3% 🔴
loader 🟢 185.9ms 🟡 202.1ms +8.7% 🔴
resolver 🟢 21.8ms 🟢 20.2ms -7.1% 🟢
checker 🟢 195.1ms 🟡 218.2ms +11.8% 🔴
validation 🟢 46.6ms 🟢 46.7ms +0.0%
 ↳ validation/@azure-tools/typespec-azure-core 🟢 7.0ms 🟢 7.7ms +8.8%
 ↳ validation/@typespec/http 🟢 5.5ms 🟢 6.6ms +19.7% 🔴
 ↳ validation/@typespec/rest 🟢 0.7ms 🟢 0.7ms -1.8%
 ↳ validation/@typespec/versioning 🔴 31.2ms 🔴 30.0ms -3.6%
 ↳ validation/compiler 🟢 1.9ms 🟢 1.6ms -15.7%
linter 🟢 142.3ms 🟢 156.4ms +9.9% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/auth-required 🟢 0.0ms 🟢 0.0ms +10.4%
 ↳ linter/@azure-tools/typespec-azure-core/bad-record-type 🟢 0.3ms 🟢 0.3ms +0.4%
 ↳ linter/@azure-tools/typespec-azure-core/byos 🟢 6.5ms 🟢 6.8ms +5.1%
 ↳ linter/@azure-tools/typespec-azure-core/casing-style 🟢 0.7ms 🟢 0.7ms +10.2%
 ↳ linter/@azure-tools/typespec-azure-core/composition-over-inheritance 🟢 0.1ms 🟢 0.1ms -17.3%
 ↳ linter/@azure-tools/typespec-azure-core/documentation-required 🟢 0.9ms 🟢 1.0ms +2.0%
 ↳ linter/@azure-tools/typespec-azure-core/friendly-name 🟢 0.7ms 🟢 0.6ms -4.8%
 ↳ linter/@azure-tools/typespec-azure-core/key-visibility-required 🟢 0.2ms 🟢 0.2ms +10.2%
 ↳ linter/@azure-tools/typespec-azure-core/known-encoding 🟢 0.3ms 🟢 0.3ms +9.6%
 ↳ linter/@azure-tools/typespec-azure-core/long-running-polling-operation-required 🟢 0.3ms 🟢 0.4ms +17.8%
 ↳ linter/@azure-tools/typespec-azure-core/no-case-mismatch 🟢 0.3ms 🟢 0.3ms +7.2%
 ↳ linter/@azure-tools/typespec-azure-core/no-closed-literal-union 🟢 0.3ms 🟢 0.3ms +15.6%
 ↳ linter/@azure-tools/typespec-azure-core/no-enum 🟢 0.1ms 🟢 0.0ms -4.3%
 ↳ linter/@azure-tools/typespec-azure-core/no-error-status-codes 🟢 0.1ms 🟢 0.1ms +12.0%
 ↳ linter/@azure-tools/typespec-azure-core/no-explicit-routes-resource-ops 🟢 0.1ms 🟢 0.1ms +6.3%
 ↳ linter/@azure-tools/typespec-azure-core/no-format 🟢 0.6ms 🟢 0.6ms +0.9%
 ↳ linter/@azure-tools/typespec-azure-core/no-generic-numeric 🟢 0.5ms 🟢 0.5ms -5.1%
 ↳ linter/@azure-tools/typespec-azure-core/no-header-explode 🔴 20.3ms 🔴 22.6ms +11.4% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/no-legacy-usage 🟢 1.2ms 🟢 1.2ms +5.4%
 ↳ linter/@azure-tools/typespec-azure-core/no-multiple-discriminator 🟢 0.1ms 🟢 0.1ms +5.7%
 ↳ linter/@azure-tools/typespec-azure-core/no-nullable 🟢 0.3ms 🟢 0.3ms +3.1%
 ↳ linter/@azure-tools/typespec-azure-core/no-offsetdatetime 🟢 1.2ms 🟢 1.3ms +8.3%
 ↳ linter/@azure-tools/typespec-azure-core/no-openapi 🟢 2.1ms 🟢 2.1ms +3.0%
 ↳ linter/@azure-tools/typespec-azure-core/no-private-usage 🟢 2.1ms 🟢 2.1ms +1.5%
 ↳ linter/@azure-tools/typespec-azure-core/no-query-explode 🔴 20.2ms 🔴 23.4ms +16.0% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/no-response-body 🔴 26.4ms 🔴 28.7ms +8.6% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/no-rest-library-interfaces 🟢 0.0ms 🟢 0.0ms -7.0%
 ↳ linter/@azure-tools/typespec-azure-core/no-route-parameter-name-mismatch 🟢 5.2ms 🟢 5.9ms +14.3%
 ↳ linter/@azure-tools/typespec-azure-core/no-rpc-path-params 🟢 0.2ms 🟢 0.2ms +20.2%
 ↳ linter/@azure-tools/typespec-azure-core/no-string-discriminator 🟢 0.1ms 🟢 0.1ms -0.5%
 ↳ linter/@azure-tools/typespec-azure-core/no-unknown 🟢 0.2ms 🟢 0.2ms +11.1%
 ↳ linter/@azure-tools/typespec-azure-core/no-unnamed-union 🟢 0.4ms 🟢 0.4ms +14.6%
 ↳ linter/@azure-tools/typespec-azure-core/operation-missing-api-version 🟢 0.2ms 🟢 0.2ms +1.6%
 ↳ linter/@azure-tools/typespec-azure-core/request-body-problem 🟢 0.3ms 🟢 0.3ms +0.5%
 ↳ linter/@azure-tools/typespec-azure-core/require-versioned 🟢 0.0ms 🟢 0.0ms -10.8%
 ↳ linter/@azure-tools/typespec-azure-core/response-schema-problem 🔴 22.8ms 🔴 26.3ms +15.5% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/rpc-operation-request-body 🟢 0.3ms 🟢 0.4ms +15.6%
 ↳ linter/@azure-tools/typespec-azure-core/spread-discriminated-model 🟢 0.3ms 🟢 0.3ms +17.3%
 ↳ linter/@azure-tools/typespec-azure-core/use-standard-names 🟢 6.0ms 🟢 6.4ms +6.5%
 ↳ linter/@azure-tools/typespec-azure-core/use-standard-operations 🟢 0.1ms 🟢 0.1ms +10.0%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-agent-base-type-child-resources 🟢 3.8ms 🟢 4.8ms +25.9%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-agent-base-type-lifecycle-operations 🟢 0.0ms 🟢 0.0ms -17.5%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-common-types-version 🟢 3.8ms 🟢 4.4ms +15.4%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-custom-resource-no-key 🟢 0.1ms 🟢 0.1ms +23.9%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-custom-resource-usage-discourage 🟢 0.1ms 🟢 0.1ms +9.9%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-delete-operation-response-codes 🟢 1.1ms 🟢 1.3ms +13.8%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-no-path-casing-conflicts 🟢 4.4ms 🟢 4.9ms +10.2%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-no-record 🟢 0.4ms 🟢 0.4ms +7.0%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-post-operation-response-codes 🟢 0.5ms 🟢 0.5ms +19.9%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-put-operation-response-codes 🟢 0.0ms 🟢 0.0ms +9.1%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-action-no-segment 🟢 0.2ms 🟢 0.3ms +19.2%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-duplicate-property 🟢 0.1ms 🟢 0.1ms +18.9%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-interface-requires-decorator 🟢 0.0ms 🟢 0.0ms +12.1%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-invalid-action-verb 🟢 0.1ms 🟢 0.1ms +22.8%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-invalid-envelope-property 🟢 0.1ms 🟢 0.1ms +5.2%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-invalid-version-format 🟢 0.0ms 🟢 0.0ms +9.6%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-key-invalid-chars 🟢 0.2ms 🟢 0.3ms +13.0%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-name-pattern 🟢 0.0ms 🟢 0.0ms -10.7%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-operation 🟢 0.2ms 🟢 0.2ms -1.2%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-operation-response 🟢 4.5ms 🟢 5.2ms +14.3%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-patch 🟢 0.3ms 🟢 0.4ms +26.5%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-path-segment-invalid-chars 🟢 0.2ms 🟢 0.2ms +16.1%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-provisioning-state 🟢 0.1ms 🟢 0.1ms +18.8%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/beyond-nesting-levels 🟢 0.1ms 🟢 0.1ms +23.6%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/empty-updateable-properties 🟢 0.2ms 🟢 0.2ms +10.3%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/improper-subscription-list-operation 🟢 0.0ms 🟢 0.0ms +3.0%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/lro-location-header 🟡 13.5ms 🟡 14.9ms +10.9% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/missing-operations-endpoint 🟢 0.0ms 🟢 0.0ms +20.0%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/missing-x-ms-identifiers 🟢 0.3ms 🟢 0.3ms +11.1%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/no-empty-model 🟢 0.1ms 🟢 0.2ms +10.5%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/no-override-props 🟢 0.1ms 🟢 0.1ms +24.8%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/no-resource-delete-operation 🟢 0.2ms 🟢 0.2ms +19.4%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/no-response-body 🔴 22.2ms 🔴 25.0ms +12.9% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/patch-envelope 🟢 0.1ms 🟢 0.2ms +19.2%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/resource-name 🟢 0.1ms 🟢 0.2ms +17.7%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/secret-prop 🟢 2.9ms 🟢 2.6ms -11.0%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/unsupported-type 🟢 0.3ms 🟢 0.4ms +17.9%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/version-progression 🟢 0.0ms 🟢 0.0ms -2.2%
 ↳ linter/@azure-tools/typespec-client-generator-core/property-name-conflict 🟢 1.1ms 🟢 1.2ms +10.6%
 ↳ linter/@azure-tools/typespec-client-generator-core/require-client-suffix 🟢 0.2ms 🟢 0.2ms -6.4%
emit 🔴 6.07s 🔴 6.44s +6.1% 🔴
 ↳ emit/@azure-tools/typespec-autorest 🟢 171.1ms 🟢 185.1ms +8.2% 🔴
 ↳ emit/@azure-tools/typespec-python 🔴 4.36s 🔴 4.74s +8.8% 🔴
 ↳ emit/@typespec/http-client-js 🔴 1.25s 🔴 1.27s +1.5%
 ↳ emit/@typespec/openapi3 🟢 155.2ms 🟢 166.4ms +7.2% 🔴
 ↳ emit/@typespec/openapi3/compute 🟢 136.3ms 🟢 145.5ms +6.8% 🔴
 ↳ emit/@typespec/openapi3/write 🟢 18.9ms 🟢 20.3ms +7.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

timotheeguerin commented Jun 18, 2026

Copy link
Copy Markdown
Member

@copilot regnerate the sample and format

@timotheeguerin
Regenerate widget-manager sample output and format snapshot
9986be3 
Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>

Copilot AI commented Jun 18, 2026

Copy link
Copy Markdown
Contributor Author

@copilot regnerate the sample and format

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

Copilot AI requested a review from timotheeguerin June 18, 2026 14:18
@timotheeguerin
Format widget-manager auth model declaration
722a4df 
Co-authored-by: timotheeguerin <1031227+timotheeguerin@users.noreply.github.com>

Copilot AI commented Jun 23, 2026

Copy link
Copy Markdown
Contributor Author

@copilot regnerate the sample and format

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

@timotheeguerin timotheeguerin marked this pull request as ready for review June 24, 2026 17:53
@azure-sdk-automation

azure-sdk-automation Bot commented Jun 24, 2026

Copy link
Copy Markdown

No changes needing a change description found.

@azure-sdk-automation

azure-sdk-automation Bot commented Jun 24, 2026

Copy link
Copy Markdown

You can try these changes here

🛝 Playground 🌐 Website

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@timotheeguerin timotheeguerin Awaiting requested review from timotheeguerin timotheeguerin is a code owner
@bterlson bterlson Awaiting requested review from bterlson bterlson is a code owner
@markcowl markcowl Awaiting requested review from markcowl markcowl is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

@timotheeguerin timotheeguerin

Copilot code review Copilot

Labels

stale Mark a PR that hasn't been recently updated and will be closed.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Bug]: Data plane sample in TypeSpec Azure playground should have descriptions on security schemes

2 participants

@timotheeguerin