Azure / Azure/azure-rest-api-specs
[Proposal] New extension to mark features in swagger.
- 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
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