Publish the schemas in a human-readable form

[blootsvoets]

We could do this in a GitHub.io page just posting the javadoc. There is a avrodoc documentation generator but that doesn't support references to other types (Such as restapi/app/application.avsc refers to restapi/app/server_status.avsc.

[fnobilia]

Does it supports only embedded schemas?

[blootsvoets]

Yes: ept/avrodoc#19. And its unmaintained. I haven't found an alternative so far though...

[fnobilia]

At present, for the Rest API is almost impossible to avoid embedded schemas, we will end up with a single .avsc file containing almost all schemas. I don't think it can be easily maintained.

It is in my plan to structure the Rest API project to improve the modularisation and to simplify future integrations. I may try to restructure the Dataset schema to mitigate its dependencies. If this is a low priority task and we can wait a little bit, I will get back to you with a more precise solution.

I see your point of publishing schemas in a human-readable form. I totally agree. However, are we sure we want to rely on a project that is unmaintained since 4 years? It is quite risky.

[blootsvoets]

No on the contrary, I think we shouldn't use Avrodoc. But we should have some form of documentation. Perhaps the route avsc -> JSON schema -> doc would also provide proper documentation, although we might loose some information in the conversion.

[blootsvoets]

BTW: by putting all files in a single protocol file, and putting them in an order where each type is defined before it is referenced, avrodoc seems to work fine. For now, that's quite some manual work though.