[Epic][TypeSpec Authoring] Auto-Scaffold for a brand-new service onboarding
- Dominant language
- C#
- Stars
- 135
- Forks
- 260
- Avg merge
- 3d 1h
- Merged PRs (30d)
- 143
Description
hOverall Experience in One Line
> “_Answer 5–7 questions. We’ll scaffold your Azure REST API specs folder + TypeSpec project + first version skeleton, aligned with Azure guidelines._”
Break the experience into 3 stages, aligned with the goals
**Stage 1 - Repo & Versioning Grounding (Folder Structure)**
User Goal - Understand the required folder structure per Azure Service Versioning Guideline without reading a giant doc.
Experience Style - ask 2–3 questions, then instant scaffold + a short visual explanation.
Required Inputs:
- Service type: management plane or data plane
- Service identity: resource provider name (for ARM) or service name (for data plane)
- Initial API version: 2026-01-01, or 2026-01-01-preview
- Is this your first service onboard to azure-rest-api-specs? Yes - create full structure; No - only add new version under existing path
Teaching Moment - [service versioning workflow](https://aka.ms/azbreakingchangespolicy) and [single preview policy](https://learn.microsoft.com/en-us/azure/developer/intro/azure-service-sdk-tool-versioning#preview-versions)
**Stage 2 - Create the TypeSpec Azure Project**
User Goal - Create a new TypeSpec Azure project for Management Plane or Data Plane with minimal friction.
Required Inputs:
- Plane (pre-filled from Stage 1): Management/Data
- Desired languages or SDK targets: all supported languages - Python, Java, JS, Go, .NET
- Top-level namespace / service name (pre-filled from Stage 1)
**Stage 3 - Versioning Strategy + First Versioning Authoring + First Resource Type Adding**
User Goal - Understand how to version with TypeSpec and begin authoring the first version
Required Inputs:
- What lifecycle stage is this API? Under development - preview version; Ready for external partners - preview; Generally available - stable version
- Will you maintain multiple active version at once soon? No; Yes, GA + one Preview
- Short description of first resource types and its operations
Contributor guide
Research direction
No files, tests, or entry points are named. Start by reviewing the three-stage flow and the linked Azure versioning guidance, then define the scaffold outputs and supported answers for each required input. Done means a newcomer can answer the questions and receive the stated folder structure, TypeSpec project, version skeleton, and initial resource scaffold.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- azure
- Domain
- developer-experience, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100