You may want to expand your proposal to add more details for those not familiar with either Beego or Swagger. (Is Beego relevant to this proposal?).

But in the past, all proposals around adding @MagicAnnotations or other special comments to godoc have been rejected. I don't see how this one would be different.

I have successfully used @adams-sarah's project https://github.com/adams-sarah/test2doc in the past. It uses the Apiary format rather than Swagger, but you could extend it to swagger with some engineering effort.

The nice thing is that it does not require creating comments in godoc. The documentation is generated based on your http handler tests.

If you wanted to, you could write the Example format tests to work with test2doc so they'd show up both as godoc examples and as REST API documentation.

As Brad said, we aren't going to change the godoc comment format to hide various lines. @groob's comment about test2doc sounds like a better solution.