Improve Tree token parser documentation

maririos commented 4 months ago

See how we can collect the model code comments and pusblish them for the team to consume.
Keep documenting each key feature in APIView and how these are accomplished in v2.
[ ] a script of some kind (though preferably not Powershell) that would allow you to evaluate a provided tokenfile against the generated JSON schema. Every inner-loop dev will need to do that, so that should live here.
[ ] Some kind of automated test that would compare test tokenfiles against both the JSON schema and the server parsing logic. This will help ensure that if the server logic changes, that the TypeSpec and JSON schema and likewise updated.

maririos commented 3 months ago

We have decided to use TypeSpec to document the Tree Token API. We will generate the JSON schema from it and publish it so language parsers can leverage this when working on their parsers

lmazuel commented 3 months ago

We have decided to use TypeSpec to document the Tree Token API. We will generate the JSON schema from it and publish it so language parsers can leverage this when working on their parsers

Love it.

I also think that I assume on the server side there is some integration tests, it would be nice to validate those JSON that are used as integration tests as well with the schema. Idea is trying to ensure that the server is not consuming JSON that doesn't respect it's own schema.

And seriously (I'm really not joking), as we have C# server side generation from TypeSpec now, we could investigate generating the server layer from that TypeSpec as well. This way, APIView wouldn't need to handle any deserialization or HTTP code manually, and can focus on high level code. Also, this would demonstrate that the TypeSpec is correct, by definition, since the server code couldn't access something not defined in the TypeSpec. It's precisely why TypeSpec was designed this way: generate server code and client code (in that case models generation for language writer), and given both side comes from the same source of truth, we are guaranteed that the interoperability layer will never get in the way, reducing bugs and maintenance.

tjprescott commented 3 months ago

Is the JSON schema published?

maririos commented 3 months ago

Is the JSON schema published?

Not yet

maririos commented 1 month ago

More information: https://github.com/Azure/azure-sdk-tools/blob/main/tools/apiview/parsers/CONTRIBUTING.md

Azure / azure-sdk-tools

Improve Tree token parser documentation #8517