Azure / Azure/azure-sdk-tools

[TypeSpec Authoring] Support API example assessment

Open
#16,825 0 comments 0 reactions 0 assignees View on GitHub
AzSDK Tools Agent dev inner loop needs-triage
Dominant language
C#
Stars
135
Forks
260
Avg merge
3d 2h
Merged PRs (30d)
130

Description

## Goal

Assess whether API examples remain complete and correct for the changed TypeSpec API surface.

## Scope

- Identify examples associated with newly added or materially changed operations and models.
- Detect missing examples for workflows where examples are expected.
- Detect stale examples that no longer match request or response schemas, parameters, required properties, enum values, defaults, errors, paging, or long-running behavior.
- Validate examples against generated artifacts or the TypeSpec semantic model where possible.
- Link findings to the relevant TypeSpec declaration and example file.
- Avoid duplicate findings when one shared example issue affects multiple operations.

## Acceptance criteria

- Missing examples for representative new workflows are detected.
- Stale request, response, parameter, enum, and model examples are detected.
- Valid examples do not produce findings.
- Findings clearly identify the required example update and include source links.
- Missing validation evidence produces an explicit blocked/not-assessed result.
- Tests cover missing, stale, valid, shared, and unavailable-evidence cases.

Contributor guide

Open the contributing guide

Research direction

Start by mapping the TypeSpec declarations, example files, generated artifacts, and semantic model involved in API example assessment. Define how missing, stale, valid, shared, and unavailable-evidence cases should be represented, then add tests demonstrating the acceptance criteria and confirm findings include source links without duplicates.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
api, testing, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.