Produce a reviewed OpenAPI file for Kiota

[njaci1]

In generating kiota service libraries, a PR has to be reviewed for each language's service library. The review will always yield the same result based on the OpenAPI from the CSDL to OpenAPI conversion. We can move the review part to the OpenAPI generation step to enhance the process and make it more efficient.

More details on this issue: Our weekly generation process for service libraries effectively looks like this (simplified):

• Workloads/services push their CSDL metadata changes to the repo AGS uses
• AGS publishes those changes every Wednesday
• We grab the updated CSDL every Tuesday
• We apply "fixes" to it, aka XSL transforms
• We convert it to OpenAPI
• We generate the code for every language
• We generate pull requests for every language
• We review each pull request for each language.
• A new release of a given language and graph version is made available.

The steps outlined here are mostly automated, except when it comes to the review part. When it comes to reviewing the languages changes, because Kiota is deterministic and reliable, we're effectively reviewing the same OpenAPI changes times X languages we support. Which is wasteful. In addition to the manual review, those repos have CI in place that'd catch any major breakage.

Recommendation The suggestion is we stop reviewing changes at the language level but instead do it at the OpenAPI level to help save time. To enable that, we'd need something like Hidi being capable of doing a diff between two OpenAPI descriptions. It'd effectively return a rich report (see the visualization work Darrel has been doing) and a 0 exit code when "changes are good" (only additions, no removals or renaming) It'd return the same report, exit code 1, and errors in the logs outlining any defect (removals, renaming)

We could then integrate that command to our pipeline and update the metadata repo settings so that it requires PRs on update, and the whole generation pipeline will pause until the PR is reviewed and merged. Having a machine readable format of the differences would also be useful to generate change logs, which has been a long awaited request from the community.

[garethj-msft]

We should not build any diffing functionality before we have investigated existing industry tooling such as https://www.oasdiff.com