api - 为 API 库生成更好的 GoDoc

Question

我用 Go 实现了一个典型的 REST API 库。但是由于端点的数量和不同的数据结构，端点之间几乎没有共享的数据结构，项目的 GoDoc 非常困惑:

它现在的结构方式使得很难看到实际函数返回的内容，需要大量滚动文档才能找到与数据相关的结构。

端点都是 API 结构的一部分，因为它们可以在 API 调用之间共享身份验证状态，这导致它们全部列在 GW2Api 结构下方，而不是它们关联的数据结构。

除了 GoDoc 之外，还有什么好的方法可以让库 API 更清晰吗？向函数调用添加注释？

Answer 1

我认为很好的一个 api 包的例子是 github 包装器:https://godoc.org/github.com/google/go-github/github .

如果你有一个大的 api，有点大的 godoc 是不可避免的。请注意，而不是直接从 client 定义一百万个方法。 ，核心对象定义了多个“服务”对象，允许它们将方法划分为逻辑组。我可以从您的 API 中的方法中看到多个可能的组。

我不认为有一种非常好的方法可以在不对您的 api 进行重大更改的情况下将方法与它们作用或返回的结构类型分组。而是期望人们寻找他们想要执行的操作，并从那里链接到特定的结构类型以供引用。