[ANN] Request For Comments: Golax Documentor

95 views

Skip to first unread message

Gerardo Oscar JT

unread,

Feb 20, 2016, 7:44:16 PM2/20/16

to golang-nuts

Hi,

Few weeks ago I released golax framework and now I am working on an easy way to self-document the REST API, and an 'apidoc' builder to expose documentation.

There are some points I would like to comment about the apidoc builder:

#1 The approach I am following is to add explicit documentation when the API is being defined. I like the idea of maintaining documentation + implementation as close as possible, but I am afraid of the code readability could be extremely bad. Here is an screenshoot of the diff with the new approach:

Original example: https://github.com/fulldump/golax/blob/master/example/main.go

New example: https://github.com/fulldump/golax/blob/experiment/autodocumentation-api/example/main.go

#2 Regarding the moment the documentation is generated, the proposal is online, I mean, the process generate it on the fly reading `Node` structures while the process is running. Other alternative could be running the binary with a flag like --gen-api-doc.

#3 Document errors. I am thinking about documenting errors in the same way the description is added, (explicit) but it requires synchronize doc and code manually. If a new error is added in the code, a new entry has to be added to the documentation. It would be great the documentation system collect all possible errors automatically from the unit tests.

#4 The automatic documentation should generate also something similar to swagger but there is a lot of use cases to treat, parameters in the URL, different bodies with parameters, validations etc... A generic way to add specific uncovered cases would be great.

#5 According to Go philosophy, would be better a new code repository for the apidoc builder or all in the same one?