microsoft
Write version to OpenApiDocument
Currently, the exact OpenAPI version is not written to OpenApiDocument.
This doesnt seem trivial to read without converting the entire thing to yaml ourselves.
Could this be added?
Can you help me understand how you might use this property? There is only one OpenAPIDocument object and it represents an OpenAPI v3.0.x version. When we read in OpenAPI documents we translate them from their "on disk" format to a V3 format in memory. We can write back out to V2 by doing a translation while writing.
What does it mean to have an OpenApiDocument that has version = 2.0? The most I can infer is that when I read it in, it came in as a v2 document. You can get that information from looking at the OpenApiDiagnostic object https://github.com/microsoft/OpenAPI.NET/blob/89439eebb1a9136ee468525e636bfd88411807a6/src/Microsoft.OpenApi.Readers/OpenApiDiagnostic.cs#L23
When we implement OpenAPI 3.1, the OpenAPIDocument will represent a 3.1 version and writing to 2.0 and 3.0 will require translation.
We are using it to add tooling on top.
We are using this library to add rulesets on top of the API specification, but are forwarding the original specification down the pipeline.
The OpenAPI document changed quite a bit between minor version and we have other tools that dont support certain versions for instance.
Or some linters dont allow certain properties from certain versions.
Using diagnostics only gives us 2.0 or 3.0, and was not an obvious choice. Where Version (which is a required property in all versions) was more straight forward (and a part of the spec). but Major.Minor.Patch (the full version) would be nice to have.
I understand that the library was not meant as an abstraction for api specs of different versions, but rather a translation from any to newest, if you will. - In this case, It doesnt make sense to have the "original" version stamped on the deserialized document.
When we implement 3.1 we will include the 3.1 in the diagnostics property. The patch version has no impact on the document as patch versions are only used for clarifications in the specification.
With this being the case do you still see a need for the version in the document, or can I close your PR?
Im going to quote myself here
I understand that the library was not meant as an abstraction for api specs of different versions, but rather a translation from any to newest, if you will. - In this case, It doesnt make sense to have the "original" version stamped on the deserialized document.