1
xuanbg 2020-11-26 13:10:41 +08:00
手写 MD 文档就不麻烦了,复制-粘贴改一改就好,效率飞起
|
2
qW7bo2FbzbC0 2020-11-26 13:23:45 +08:00 1
用 c# 或者 spring 多好,django 的 swagger 都不是很方便,因为这个原因弃用 go 做 web 服务
|
3
charmToby 2020-11-26 13:44:42 +08:00
同求,有类似机制的,楼主记得艾特我。
|
4
lingxi27 2020-11-26 14:00:41 +08:00 2
换种思路,文档->代码
|
5
DoctorCat OP |
6
DoctorCat OP @hjahgdthab750 Python 的话 FastAPI 可以自动生成,不需要人肉介入。
|
7
qW7bo2FbzbC0 2020-11-26 14:17:26 +08:00 1
@DoctorCat #6 fastapi 不能像 flask django 那样直接用 py 文件启动吧,好像要在系统上装什么来着
|
8
qW7bo2FbzbC0 2020-11-26 14:20:09 +08:00
@hjahgdthab750 #7 没有超级用户权限,我选择绕开 fastapi,本来还是挺不错的项目
|
9
TangMonk 2020-11-26 14:21:45 +08:00 via iPhone
Ruby 的 grape 配合 swagger 异常好用,全自动生成,连注释都不写
|
10
haitaotao 2020-11-26 14:23:09 +08:00 via iPhone
如果是 api 的建议先使用 protobuf 等 idl 描述,再动生成文档和代码。
我们也是苦文档不更新久矣。最后搞了个[sniper 框架]( https://github.com/bilibili/sniper),具体的设计思路可以参考[这篇文章]( https://zhuanlan.zhihu.com/p/69029677)。在生产环境跑了两年多了,效果还不错。 |
11
charmToby 2020-11-26 14:24:16 +08:00
@hjahgdthab750 FastAPI 只需要安装 uvicorn 就可以直接 py 文件启动了。
|
12
wzw 2020-11-26 14:24:34 +08:00
|
13
qW7bo2FbzbC0 2020-11-26 14:27:13 +08:00
@charmToby #11 对对,线上没有 uvicorn,也没有安装的权限
|
14
siteshen 2020-11-26 14:47:10 +08:00
有几年没用 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 2020-11-26 14:59:06 +08:00 via Android 1
学习下标准库里 go/ast go/types 几个包,自己写一个就行,一两百行完事的程序,自己需要什么就写什么,何必到处找,你找到也未必合用。
|
16
herofire 2020-11-26 15:12:52 +08:00
smartdoc?
|
17
Biebe 2020-11-26 15:37:21 +08:00 via iPhone
用 protobuf 描述借口,protoc swagger 插件自动生成
|
18
tiedan 2020-11-26 15:46:01 +08:00
protobuf
|
20
lingxi27 2020-11-26 16:00:04 +08:00
|
21
Rwing 2020-11-26 16:01:19 +08:00
考虑下 c#,直接把代码注释生成 swagger 😊
|
22
janxin 2020-11-26 16:30:28 +08:00
|
23
zqx 2020-11-26 16:35:16 +08:00 via Android
先写文档,再开发,就不慢了
|
24
DoctorCat OP |
25
yuan434356430 2020-11-26 16:42:37 +08:00
用 javaparser 静态分析代码,自动生成 Swagger 注解,我这么写过,不过只是生成了简单一点的,因为有些字段和方法是没有注释的
|
26
yuan434356430 2020-11-26 16:44:14 +08:00
因为 swagger 的注解内容都是可以从已有的代码里读取到的
|
28
siteshen 2020-11-26 16:56:17 +08:00
@DoctorCat 我用 go 写 API,没用过 framework,都是用的 library,自己手写 model + generate 通用的 model 级别的 API 。
听你这么说 APIJSON 还会接管 ORM,应该是 framework 了。 |
29
meshell 2020-11-26 17:01:08 +08:00
用 go 我还是建议手写 markdown....
|
30
sprite82 2020-11-26 17:30:17 +08:00
推荐个 apifox 功能方面挺好的,mock swagger,压测 都有,但是貌似有 cpu 占用的问题,如果有安全要求的话就别用了
|
32
jiyingze 2020-11-26 18:13:13 +08:00
smart-doc 可以根据源码注释生成文档。
|
34
saberlong 2020-11-26 22:35:28 +08:00 via Android
我也是用 golang 自带 ast 针对性写的
|
35
lidashuang 2020-11-27 11:49:23 +08:00
|
36
lidashuang 2020-11-27 11:49:47 +08:00
@charmToby Graphql 也可以考虑
|
37
lidashuang 2020-11-27 11:50:02 +08:00
@meshell 手写 你不累吗
|
38
meshell 2020-11-27 12:00:04 +08:00
@lidashuang 还好呀。说实话,go 里面写注释,然后生成还没有手写 markdown 复制粘贴快.
|
39
TransAM 2020-11-27 12:44:13 +08:00 via Android
python 不写 docstr 能自动生成文档?开玩笑
|
40
joesonw 2020-11-27 13:12:50 +08:00
go 自带 ast 包, 随便怎么玩代码生成啊.
|
41
lidashuang 2020-11-27 13:23:20 +08:00
@meshell 一个很重要的点是 代码和文档同步,fastapi 就做的很好
|