can I add extra information with annotations?

[cristianchaparroa]

I would like to add additional information to the template using some annotations over the functions handlers, something like

@Description  This endpoint to get all the users in the app
@return json
@... 
func getAllUsers(w http.ResponseWriter, r *http.Request) {
  fmt.Fprintf(w, "Hi there, I love %s!", r.URL.Path[1:])
}

And handle the route

r.GET("/api/v1/users/all", getAllUsers) 

And generate something like

This endpoint to get all the users in the app
GET: /api/v1/users/all

can I do that?

[aniketawati]

With current approach this is not possible. We generate route information at runtime, and type/function comments are not accessible at runtime.

[BrianNewsom]

One possibility is something like adding an http header that is interpreted and then removed by the yaag middleware. Not super elegant, but would do the trick. Could even have a utility function to add it with a function call or something. Still wouldn't be an annotation though. Thoughts @aniketawati?

[BrianNewsom]

@cristianchaparroa - Implemented a quick possible solution here, check out examples/core/server.go for the usage. Not quite an annotation, but works fairly similarly.

@aniketawati - not sure what you think of something like this, it is a bit of a stretch of the original usage, but it's kind of nice to have as a feature. This is just an MVP but I wanted to let you take a look before I did too much more.

https://github.com/betacraft/yaag/compare/master...BrianNewsom:master?name=master#diff-04c6e90faac2675aa89e2176d2eec7d8

[aniketawati]

@BrianNewsom adding annotations in code won't be a good idea. We don't want any of this code to run in production. Every handler calling annotations package methods even when yaag is not ON, would be an overhead if you consider large loads.

Better way for implementing this would be to take the source path as a parameter in Yaag init. Get a list of handler packages in yaag init. Use https://godoc.org/go/doc to generate godoc in memory for the packages. In middleware, loop through next functions, and find their package/names through reflection, and get corresponding comments through godoc.

[aniketawati]

I have added a preliminary implementation for this in a feature branch - feature/annotations.

The annotations could go into a metadata object in Spec. While processing spec client can relate ApiCall path to Metadata and generate docs.

This is a generated sample -

{
  "ApiSpecs": null,
  "MetaData": [
    {
      "Path": "/",
      "Description": "This is a dummy handler",
      "Custom": null
    },
    {
      "Path": "/say_it",
      "Description": "This is a dummy post handler",
      "Custom": null
    }
  ]
}

Run example in examples/core/ to see this in action.