Suggestions about reusing function/method information in comments, swagger, logs, events

68 views
Skip to first unread message

brunetto

unread,
Sep 18, 2017, 3:42:19 PM9/18/17
to golang-nuts
Hi all!

Given a Go project I write for my company I have (and want) to: 

* write comments on functions/methods (at least the exported ones)
* write docs for the swagger API docs (using a personal project based on github.com/MarkSonghurst/swag and subpackages) 
* write few information to be stored in the logs or in the emitted events: function name, purpose (why the function was called), output obtained (~event result from calling the function/method), expected input and possible outputs types and status codes

A lot of information is shared and it would be very nice to avoid copy and past is over and over spreading it through the code. 
It would be great to have those information bounded in some way to the function/method but I'm open to better ways of thinking.
A struct with the information with a method returning the function seems wrong to me 
 
Can you suggest a way to reduce duplication and approach this matter in a good way?

Good to me means clean, clear to the reader, idiomatic, generic = not bound to a single web framework, play well with custom CI/CD and, most important, not insanely complicated and involuted like the standard swagger comments.  

Thanks a lot

Brunetto

Vladimir Varankin

unread,
Sep 19, 2017, 5:39:29 AM9/19/17
to golang-nuts
Hi Brunetto,

While I don't have "a take and go" solution, I have some thoughts to discuss.

What I like about swagger and openapi is the ability to abstract the way you describe your API's, from the particular implementation. This paradigm is (almost) perfectly matches to Go's code generation pattern. 

Looking at how projects like gRPC do things, feels that an API description should be written using a sort of a special DSL, which could be used to produce implementations (or stubs) for a particular framework. I might be wrong, but it looks like Goa (https://github.com/goadesign/goa) uses exactly the same approach.

Right now I can't think of any other way that would be integrated into the code, so docs and the implementation stayed fresh, and wouldn't bring too much overhead to the API's runtime.

What do you think about code generation approach?

Cheers,

Vladimir
Reply all
Reply to author
Forward
0 new messages