azure-service-operator icon indicating copy to clipboard operation
azure-service-operator copied to clipboard

Use Swagger as a single source of truth

Open matthchr opened this issue 4 years ago • 0 comments

Describe the current behavior We use both the Swagger and ARM JSON schemas as the source of truth for our types. This has some problems:

  1. The ARM JSON schema isn't entirely autogenerated, which means that there are sometimes manual mistakes.
  2. At the same time, it's mostly autogenerated from the Swagger, which means its source of truth and is really the Swagger. In places where it's not autogenerated from the Swagger they're actively trying to fix that.
  3. The generator has some issues, for example not excluding properties that are entirely readonly that we end up having to work around.

We also have to read the Swagger in order to generate the Status types, so we're already doing the work to parse it as well. We end up spending some effort trying to reconcile the two views of the world by effectively guessing at/understanding what the ARM JSON schema generator has done. Some examples of this are _childResource shenannigans and how they deal with resourceBase (see #1730)

Describe the improvement Use only the Swagger as the source of truth. We can refer to for example the bicep type generator which does exactly this already. It's also worth noting that even the ARM team didn't use the ARM JSON schemas to generate the bicep types, they used the Swagger.

This would be a big change though.

matthchr avatar Aug 27 '21 22:08 matthchr