Reconsider Deprecating Extensions.ApiDescription.Client #62980
Description
Is there an existing issue for this?
- I have searched the existing issues
Is your feature request related to a problem? Please describe the problem.
I have recently been in the process of migrating our old NSWag.MSBuild-based half-baked custom implementation for compile-time API Client generation over to Microsoft.Extensions.ApiDescription.Client which very clearly offered support for all of the functionality we need and in a better easier to understand/use package. A good chunk of the way through the effort, I stumbled on this open announcement issue ( aspnet/Announcements#518 ) which indicates that everything I'm doing is about to be deprecated 😭😅
I've come to make an argument for reconsidering this deprecation. For teams that manage their build processes primarily with MSBuild there is a lot of benefit to having a pre-defined set of item definitions/properties/targets/extension points for this very common activity. We're currently using Exec with a combination of custom properties/items provided via internal NuGet packages/custom project SDKs and after a few generations of occasional difficulties with orchestrating command line tool timing between multiple projects within a solution we saw there was a first-party way to do this and were excited to move to something likely to be more reliable. Our implementation was not as clean as the abstraction provided in this package and it's clear you all have stronger expertise for patterns and practices with MSBuild which we can learn from. That said, we follow the same patterns across many solutions/repositories by leveraging NuGet/SDKs/MSBuild to standardize build behaviors and this solution looks really good to us. Of particular improvement for our environment is the OpenApiProjectReference for establishing build dependency properly and automatically extracting the spec document path from the API project's common MSBuild configuration.
If I'm understanding the announcement correctly, one of the main arguments for deprecation seems to be that it's
tightly coupled to certain generators
which I imagine are based around it primarily supporting NSwag in its inception. I should think even if a larger portion of the onus were to move to the vendor packages (like NSwag.ApiDescription.Client) for building the input parameters/determining behavior around outputs, I think it would be helpful for us folks preferring MSBuild over custom scripts running command line tools between projects to have a framework for common behavior. Pretty much all API client code generators can benefit from knowing the output spec path from the API--especially given there's built-in functionality for generating the doc now--and want to run after it's generated and before the Client project is compiled, plus the design-time compilation support is an added bonus we didn't have in our command-line Exec-based implementation). Could we consider keeping this around and if we want it to be less vendor-specific consider evolving it into something that different vendor packages can leverage instead of providing an out-of-box implementation?
As for other reasons for deprecation:
The package has seen minimal updates and maintenance since its introduction.
This seems like it could be a counter-argument for
Removing the package reduces maintenance burden and clarifies the recommended workflow for client generation
but is otherwise possibly an indicator for how little maintenance something so common/simple might really require (i.e. it is more "stable" than some things which see more frequent need for updates across versions). As for making the recommended workflow "more clear" I'm not so sure it does; if I have a Client project in the same solution as the Server project which share a Contracts library (and they have a conceptual build order dependency) what exactly is the recommended workflow for taking the output spec from one project and having that become an input for generation in the next project building within the solution; what is the most appropriate means to enforce dependency and configure the path to the (intermediate?) spec output file in consuming projects. The CLI tools seem mostly to provide guidance to build one project then call a CLI tool then build another project which is a less than ideal flow for teams preferring to work in Visual Studio and just use Build Solution, F5 debugging, or executing tests from the Test Explorer, which seems to rebut the final change reason about
making the MSBuild middle-layer redundant
I guess it's reasonable to expect us all to implement generation to our own preference, but it seems like we'll end up with a lot of redundant implementations throughout the world, from my perspective.
Describe the solution you'd like
Common integration points which leverage shared knowledge across MSBuild project references to automatically determine the output path for specs generated via OpenApiGenerateDocuments, preferably via continued built-in support for OpenApiProjectReference.
If not continuing support for the NSwagCSharp output type, perhaps a PR moving some existing functionality over to NSwag.ApiDescription.Client in such a way that it extends a shared target that other packages could similarly migrate to (e.g. a kiota-specific package, perhaps maintained in their repository?).
Additional context
No response