Expose JsonPointer for each IOpenApiElement

[Fresa]

It would be nice to be able to back trace to a context in the original OpenAPI document.

Example: Get a pointer to the original parameter spec which can be used by a code generator given the original document.

Example:

OpenApiDocument document = ...;
var pointer = document.Paths.First().Value.Parameters.First().JsonPointer;
Console.WriteLine(pointer);
// #/paths/~1pets/get/parameters/0

Describe the solution you'd like
Expose a JsonPointer in IOpenApiElement.

Describe alternatives you've considered
I'm not aware of any alternatives, except serializing an element, which might differ from the original json node, and doesn't include a pointer to the original document.

Additional context
N/A

[baywet]

Hi @Fresa
Thank you for using the SDK and for reaching out.

There are a couple of reasons why I think we CAN'T implement this in the library:

1. The shape of documents varies widely between some of the versions, and the library performs conversions. What would that mean for the new pointer property? Should it provide the location in the source document? or for the latest representation the library understands?
2. Not all instances of OpenApiDocument come from something that's been deserialized, it could have been built from the object model.
3. The serialization order is not known in advance.
4. The serialization version is not known in advance.
5. (minor) The serialization format is not known in advance, even though I doubt a lot of people implement custom serialization formats (which is technically invalid according to the specification).

Unless we can provide clear answers to those remarks, thus ensuring a pointer that's provided by the API will be deterministically resolved when used, I don't think we could provide such a feature.

We might solve some of those issues by providing a string GetJsonPointer(OpenApiSpecVersion version) method instead of a property. But then again, we don't know in which order collections might be serialized in advance, some of the elements might not exist for some versions of the OpenAPI specification etc...

Let me know if you have any additional comments or questions.

[Fresa]

Perhaps the parser could expose a map between IOpenApiElement and pointers? Then it would only be relevant when parsing a document, not serializing it. However I have seen places in the SDK where it generates objects that was not defined in the spec parsed. Maybe those would be mapped to a null pointer? 🤔

[baywet]

Thank you for the additional information.

So in your scenario, you only care about the pointer to the source document (as in file) the document (as in OpenApiDocument) was deserialized from?
If there's a subsequent serialization done from this OpenApiDocument, you don't want to use those pointers against that newly serialized representation?

[Fresa]

exactly!

[baywet]

Thank you for the additional information.

This is most likely too narrow of a use case by itself.

We might be able to accept a pull request that does both this, and also provides the same information upon serialization.

In any case, this is a large set of changes, the team is not founded to implement that at the moment. Is this something you'd like to submit a pull request for provided some guidance?