V2EX = way to explore

V2EX 是一个关于分享和探索的地方

已注册用户请登录

The Go Programming Language

http://golang.org/

Go Playground

Go Projects

Revel Web Framework

smartdoc647 2023-12-27 10:26:45 +08:00 2294 次点击

这是一个创建于 652 天前的主题，其中的信息可能已经有所发展或是发生改变。

smart-doc 作为一个 java 语言的 API 文档生成工具，在国内非常的受欢迎（质疑的可以搜索百度搜索查看相关信息数量），也有不少的国内知名企业在使用，例如：科大讯飞、小米、同程旅行、蚂蜂窝、顺丰、申通、快手等。随着社区的发展，社区很多同学也给我们提出了多语言的支持，但是社区人力有限，我们一直没有去支持别的语言。

目前 golang 在国内大型企业也是一门比较受欢迎的语言，因此我们下一步的 smart-doc roadmap 是支持 golang 语言。笔者当前也是以 golang 为主。

smart-doc-go 的主要功能：

以 go-swagger 等相关工具为学习模型，开发独立的 smart-doc-go
smart-doc-go 支持为 golang 语言开发生成 Open API 、Postman 、JMeter 性能测试脚本.
smart-doc-go 支持直接推送到接口文档管理系统 Torna （ Torna 在 24 年合并到 smart-doc 社区), Torna 也在科大讯飞、同程、同程数科等公司有部署落地使用。

主要是将当前 smart-doc 在 java 上一些好的功能赋能到 golang 开发生。

社区贡献奖励

smart-doc 在 2023 年 9 月份捐赠给了同程旅行，同程旅行也非常支持社区的发展。对于社区评选的 committer ，我们不仅会在国内知名的技术社区发布宣传、同时也会给予一些小礼品作为奖励，例如：社区文化衫、技术书籍等。因此我们非常欢迎愿意参与社区贡献的同学加入，在 2024 年启动对 golang 语言的支持。

smart-doc 社区也非常的稳定，从 2018 年开源依赖，已经有 50 位开发者参与了贡献。未来我们也将继续构建自己社区生态。

项目地址：

GitHub: https://github.com/TongchengOpenSource/smart-doc
Gitee: https://gitee.com/TongchengOpenSource/smart-doc

社区联系方式

发送邮件到 [email protected]
通过当前 smart-doc 社区的官方 qq 群可联系

smart-doc

Golang

社区

同程

11 条回复 2023-12-28 23:40:37 +08:00

jaycelhz

2023-12-27 11:38:05 +08:00

有要求吗

0xGnaixEuy

2023-12-27 12:26:21 +08:00 via iPhone

有什么要求吗，也想出一份力

smartdoc647

2023-12-27 12:43:45 +08:00

@0xGnaixEuy 技术没有要求，社区更多的是愿意参与贡献，新手也是可以的，慢慢搞

smartdoc647

2023-12-27 12:44:11 +08:00

@jaycelhz 没特殊要求哈，愿意的就可以参与

smartdoc647

2023-12-27 16:05:55 +08:00

社区提案 https://github.com/TongchengOpenSource/smart-doc-golang/discussions/1

imianba2zz

2023-12-27 16:49:23 +08:00

有没有想过直接通过 hook 网卡，解析 http 的方式来生成 api 接口文档。

我个人是比较厌恶在代码里面写这种注释的；

我的想法是通过 hook 网卡解析 http 数据来生成 api 接口文档，流程如下：
1. 开发在编写接口后应该是会进行自测
2. 在自测的时候就可以通过 hook 程序来抓取到请求的 http 数据。
3.通过抓取到 http 数据解析成 api 文档
4.开发人员在再这个基础上进行编辑调整（这一步类似于 apifox 的接口管理界面）
5.至于压测这方面，应为有了接口文档和真实的 http 请求数据，我觉得编写一个通用压测程序并不困难。
目前我进行了一些实践，可以通过 ebpf 技术解析到 http 数据。如果觉得有用，你们可以参考参考，哈哈。
项目地址： https://github.com/Zhouchaowen/prism

smartdoc647

2023-12-27 17:19:30 +08:00

@imianba2zz 你这个是很好思路，但是这个很难推广落地。减少了注释，但是比如像字段的注释，验证规则这些没没法通过网络数据来抓取，文档不完善让开发再去改非常难。go 框架主要是入口层面没有没法直接知道返回和入参，导致注释很多。如果你看现在 smart-doc 在 java 那块支持就很少，注释就只是描述下字段，简单写个方法用户说明。另外是像 smart-doc 在一些公司目前在 java 上是在 CI 的构建层面去工作的。压测其实并不需要自己去开发压测工具，我们的目的是生成工具需要的标准文件，然后倒入进去测试，就是支持现有的开源生态。