The godoc reference has a pretty nice view too!

At some point we'll have to nail down our apis and version them properly

GitLab has nice auto-generated documentation for their CLI as well. https://glab.readthedocs.io/en/latest/completion/index.html

This issue is becoming stale. In order to keep the tracker readable and actionable, I'm going close to this issue in 7 days if there isn't more activity.

Looking into this

I checked possible options and unfortunately, the best approach seems to be tagging API operations via Go comments and generating OpenAPI/swagger description with swag.

An alternative approach is the chi-go/docgen (official project?), which is supposed to generate Markdown/Swagger directly from chi Router, but it isn't aware of request/response entities and status codes + it leaves a lot of noise (Recover, Middleware, Logger, Prometheus, etc.).

Once we have the swagger description ready, we can generate the Markdown file with widdershins. I'm not sure about the visual effect, but it looks promissing.

EDIT:

I'm proceeding with the comments approach.

I checked possible options and unfortunately, the best approach seems to be tagging API operations via Go comments and generating OpenAPI/swagger description with swag.

I would warn about this approach. We did this in v1 and the auto generated SDK's are not ideal. Then the comments and the code go out of sync if you don't use the SDK.

An alternative approach is the chi-go/docgen (official project?), which is supposed to generate Markdown/Swagger directly from chi Router, but it isn't aware of request/response entities and status codes + it leaves a lot of noise (Recover, Middleware, Logger, Prometheus, etc.).

I have used a tool in the past where it looks at the request/response from our unit tests to generate docs. I wonder if we can auto gen this from our SDK, not the routes.

Like maybe from our sdk functions won't be too bad to parse? A lot of edge cases 😢

func (c *Client) Upload(ctx context.Context, contentType string, content []byte) (UploadResponse, error) {

Thanks for the good chat, @Emyrk and @johnstcn! I will go the standard way (@comment) but will implement a linter/validator. In the end, we could detect outdated undocumented API functions, wrong HTTP methods, and missing fields in request entities.

Ok, time for part 2.

will implement a linter/validator. In the end, we could detect outdated undocumented API functions, wrong HTTP methods, and missing fields in request entities.

plus document other API methods.