I have been asked to ‘document the API’ by a business partner for a series of UDFs that I have provided for use on client side.
Not wanting to look silly and understanding that you can query fauna directly for FQL commands, I thought I’d ask the community to see how they document UDFs for production,
hey @Darryl_Naidu, I’m not entirely sure what you are looking for. I was also hoping to hear what our community thinks about it but since nobody responded so far I’ll provide you with my insights.
Personally, I would document the parameters and return types for each UDF. To better understand your question, were you looking for something more specific? Maybe you were looking for automatic generation of documentation (Swagger style), I haven’t seen anyone do something like that in the community yet and it would probably be quite hard given how flexible Fauna is being schemaless.
Hi @darabrecht, thanks for taking the time to respond. To be honest, I am not sure exactly what I am looking for here myself aside from documentation that will ‘keep a front-end developer happy’ working with the API. Certainly some form of automated documentation (I.e. swagger / fauna GraphQL style) would be valuable. Even if it just details input/output parameters.
Currently we are using a Google sheets document which covers details around UDF input/output parameters as you have suggested though this seems like a very low order solution as I’m sure most in the community will agree.
Since posting this message, I have noticed that you can document or comment UDFs in the custom roles permissions view when allocating access permissions. I am not sure what these comments look like for the holders of these permission keys or how they can be queried as have not had time to test. If anyone has used them previously for documentation purposes, I’d love to hear how you approached it.
Thanks again
If you want to store the documentation close to the function you could also opt to store it as metadata on the UDF. Everything is a document so you could always add additional data to a UDF, maybe storing a JSON schema on there could be worth exploring?