Azure / Azure/azure-rest-api-specs

[Proposal] New extension to mark features in swagger.

Open
#779 0 comments 0 reactions 0 assignees View on GitHub
discussion feature-request internal-ms Tooling Team
Dominant language
TypeSpec
Stars
3.1k
Forks
5.9k
Avg merge
3d 2h
Merged PRs (30d)
424

Description

Adding a new extension (e.g. x-ms-feature) can enable us to mark a set of endpoints (with all of its operations), single operations or models as a Feature (e.g. Managed Disks) and then provide description of the entire feature and also state that the feature is in preview or stable. This information can be used:
1. To generate release notes per package indicating what features are exposed, which of them is in Preview mode
2. To generate a nuget/other feed release information and give developers some info of the package content right on the webpage
3. To generate static public class in C# case (or any other way of metadata) that would also expose this information. In this case it is easy to figure out what is exposed in the dll using a .net reflector like tool instead of finding the version of the dll and then trying to find the package on the nuget/webpage. We can even think about introducing a warning during build if the code is using any APIs that are marked as preview inside the package (through attributes in C#).
4. To use this information during code generation to split sources in a way that it can produce separate folders/libraries one stable and the other one Preview.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the proposed x-ms-feature extension and how the Swagger/OpenAPI specifications represent endpoints, operations, and models. Define the extension's metadata and scope before assessing its effects on release-note generation, package information, C# metadata, and stable-versus-preview code generation; done requires an agreed design.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi
Domain
api
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.