Azure / Azure/azure-sdk-tools

Update the "Define Your service APIs" screen

Open
#11,609 9 comments 0 reactions 1 assignee Claimed by @maririos View on GitHub
Engagement Experience
Dominant language
C#
Stars
135
Forks
260
Avg merge
3d 1h
Merged PRs (30d)
144

Description

Update Release Planner to update the "Define Your service APIs" screen to remove the "Using Swagger" tab. Image

Change the last paragraph on the "Using TypeSpec" tab to:

Important: TypeSpec usage for API definition is a mandatory requirement for all new (greenfield) services. PRs for existing (brownfield) services that have not transitioned to TypeSpec will receive warnings. They will start receiving errors in FY2027. This requirement is enforced by the ARM API Review Board for Management Plane and the API Stewardship for Data Plane.

If you have an existing OpenAPI based API Spec, it is HIGHLY recommended that you convert it to TypeSpec ASAP. Working with TypeSpec is significantly safer and less costly than working with Swagger/OpenAPI for both oversight boards and service teams and will allow us all to do more for less. For RP services, once the service a TypeSpec-based service, you will be able to make use of self-attesting reviews for incremental service changes rather than have to schedule in-person review times with ARM. This will be a considerable time savings for both ARM and service teams. In-person reviews will only be required for major changes or services new to TypeSpec. In general, any in-person reviews that do end up being required will be much faster. Most importantly, teams will be able to leverage TypeSpec as the overall “source of truth” in an “API First” fashion, rather than trying to keep multiple service artifacts in synch manually. Overall, teams already on TypeSpec are very happy with it and find it easier to work with than the older methods.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.