This topic created in 1994 days ago, the information mentioned may be changed or developed.
Supplement 1 · Nov 26, 2020
请别建议我手撸 markdown 之类的了，写了 10 年代码了不想继续手写 doc 了哦
Supplement 2 · Nov 26, 2020
想实现的是 RESTful 接口，而不是 RPC 接口。
Supplement 3 · Jul 7, 2021
虽然不是很满足预期，但是相对能减少些工作量，可以试试： https://github.com/swaggo/swag/blob/master/README_zh-CN.md
 |
1
xuanbg Nov 26, 2020
手写 MD 文档就不麻烦了，复制-粘贴改一改就好，效率飞起
|
 |
2
qW7bo2FbzbC0 Nov 26, 2020  1
用 c# 或者 spring 多好，django 的 swagger 都不是很方便，因为这个原因弃用 go 做 web 服务
|
 |
3
charmToby Nov 26, 2020
同求，有类似机制的，楼主记得艾特我。
|
 |
4
lingxi27 Nov 26, 2020 2
换种思路，文档->代码
|
 |
5
DoctorCat OP |
|
6
DoctorCat OP @hjahgdthab750 Python 的话 FastAPI 可以自动生成，不需要人肉介入。
|
|
7
qW7bo2FbzbC0 Nov 26, 2020 1
@DoctorCat #6 fastapi 不能像 flask django 那样直接用 py 文件启动吧，好像要在系统上装什么来着
|
|
8
qW7bo2FbzbC0 Nov 26, 2020
@hjahgdthab750 #7 没有超级用户权限，我选择绕开 fastapi，本来还是挺不错的项目
|
 |
9
TangMonk Nov 26, 2020 via iPhone
Ruby 的 grape 配合 swagger 异常好用，全自动生成，连注释都不写
|
 |
10
haitaotao Nov 26, 2020 via iPhone
如果是 api 的建议先使用 protobuf 等 idl 描述，再动生成文档和代码。
我们也是苦文档不更新久矣。最后搞了个[sniper 框架]( https://github.com/bilibili/sniper)，具体的设计思路可以参考[这篇文章]( https://zhuanlan.zhihu.com/p/69029677)。在生产环境跑了两年多了，效果还不错。 |
|
11
charmToby Nov 26, 2020
@hjahgdthab750 FastAPI 只需要安装 uvicorn 就可以直接 py 文件启动了。
|
 |
12
wzw Nov 26, 2020
|
|
13
qW7bo2FbzbC0 Nov 26, 2020
@charmToby #11 对对，线上没有 uvicorn，也没有安装的权限
|
 |
14
siteshen Nov 26, 2020
有几年没用 go 了，看到这个话题，回顾一下在 go 项目中使用 swagger 历程。
注：我也一直讨厌写不必要的 API 文档，尤其是 API 输入、输出格式等本应该能自动生成的文档。 1. 最初是自己写的代码，根据 request, response 对象生成 swagger.json 文件（ python 也自己写过……）： https://www.v2ex.com/t/390148?p=1#r_4746014 2. 后来某个项目使用过 https://github.com/MarkSonghurst/swag （印象中某些 feature 支持不够好，我还改过少量代码） 3. 另外看到其他 v 友选择过 https://github.com/Tencent/APIJSON，也许以后会尝试？ https://v2ex.com/t/556593?p=2#r_7208890 |
 |
15
reus Nov 26, 2020 via Android 1
学习下标准库里 go/ast go/types 几个包，自己写一个就行，一两百行完事的程序，自己需要什么就写什么，何必到处找，你找到也未必合用。
|
 |
16
herofire Nov 26, 2020
smartdoc?
|
 |
17
Biebe Nov 26, 2020 via iPhone
用 protobuf 描述借口，protoc swagger 插件自动生成
|
 |
18
tiedan Nov 26, 2020
protobuf
|
|
20
lingxi27 Nov 26, 2020
|
 |
21
Rwing Nov 26, 2020
考虑下 c#，直接把代码注释生成 swagger 😊
|
 |
22
janxin Nov 26, 2020
|
 |
23
zqx Nov 26, 2020 via Android
先写文档，再开发，就不慢了
|
|
24
DoctorCat OP |
 |
25
yuan434356430 Nov 26, 2020
用 javaparser 静态分析代码，自动生成 Swagger 注解，我这么写过，不过只是生成了简单一点的，因为有些字段和方法是没有注释的
|
|
26
yuan434356430 Nov 26, 2020
因为 swagger 的注解内容都是可以从已有的代码里读取到的
|
|
28
siteshen Nov 26, 2020
@DoctorCat 我用 go 写 API，没用过 framework，都是用的 library，自己手写 model + generate 通用的 model 级别的 API 。
听你这么说 APIJSON 还会接管 ORM，应该是 framework 了。 |
 |
29
meshell Nov 26, 2020
用 go 我还是建议手写 markdown....
|
 |
30
sprite82 Nov 26, 2020
推荐个 apifox 功能方面挺好的，mock swagger，压测 都有，但是貌似有 cpu 占用的问题，如果有安全要求的话就别用了
|
 |
32
jiyingze Nov 26, 2020
smart-doc 可以根据源码注释生成文档。
|
 |
34
saberlong Nov 26, 2020 via Android
我也是用 golang 自带 ast 针对性写的
|
 |
35
G2bN4dbX9J3ncp0r Nov 27, 2020
|
|
36
G2bN4dbX9J3ncp0r Nov 27, 2020
@charmToby Graphql 也可以考虑
|
|
37
G2bN4dbX9J3ncp0r Nov 27, 2020
@meshell 手写 你不累吗
|
|
38
meshell Nov 27, 2020
@lidashuang 还好呀。说实话，go 里面写注释，然后生成还没有手写 markdown 复制粘贴快.
|
 |
39
TransAM Nov 27, 2020 via Android
python 不写 docstr 能自动生成文档？开玩笑
|
 |
40
joesonw Nov 27, 2020
go 自带 ast 包, 随便怎么玩代码生成啊.
|
|
41
G2bN4dbX9J3ncp0r Nov 27, 2020
@meshell 一个很重要的点是 代码和文档同步，fastapi 就做的很好
|
Select Language