我是公司后端开发,目前公司接口使用的是 word 记录,在 svn 上 管理的。 现在一个工程的接口文档到了快 200 页,电脑编辑保存下文档真是卡的不行。
想问下大家都是管理接口文档的,最好是离线的,公司不允许接口文档上外网。
1
zsdroid 2019-06-05 11:28:29 +08:00 1
yapi
|
2
acumen 2019-06-05 11:30:21 +08:00 via iPhone 67
口口相传,分布式存储在脑海
|
3
lihongjie0209 2019-06-05 11:31:07 +08:00
既然是后端, 直接看代码.
|
4
Vegetable 2019-06-05 11:32:30 +08:00
现在是 yapi,以前也尝试过 gitbook 来做,怪不方便的.
|
5
SirLostWhite 2019-06-05 11:34:49 +08:00
一开始用的 apizza
后来转用 eolinker 还挺好用的 |
6
skiy 2019-06-05 11:36:35 +08:00
API 文档?管理平台好多。我在用的是 mindoc。
|
7
a330202207 2019-06-05 11:37:54 +08:00
showdoc
|
8
doco 2019-06-05 11:38:21 +08:00
之前是 showDoc, 现在是 YAPI, 然而后台都不喜欢写接口文档
|
9
rexyan 2019-06-05 11:39:29 +08:00
跟着项目走,传 git
|
10
chinvo 2019-06-05 11:40:37 +08:00 via iPhone 1
openapi + web ui
|
11
shuipoqian 2019-06-05 11:42:37 +08:00
yapi , 同时后端集成了 springfox 生成 swagger 文档, 然后 swagger 的文档可以直接导入到 yapi
|
12
kevinlm 2019-06-05 11:46:16 +08:00 via iPhone 9
一杯茶,一盒烟,一个参数传一天
|
13
razaura 2019-06-05 11:50:15 +08:00 1
swagger
|
14
introle 2019-06-05 11:51:02 +08:00 via iPhone 1
swagger +1
|
15
Caballarii 2019-06-05 11:53:21 +08:00
肯定 swagger 啊,能直接试比看文档强多了好吧
|
16
pengjl 2019-06-05 12:00:38 +08:00
swagger+1
|
17
zhuwd 2019-06-05 12:13:07 +08:00 via iPhone
yapi
|
18
cccy0 2019-06-05 12:25:15 +08:00
postman
|
19
fengxianqi 2019-06-05 12:28:44 +08:00
内网部署 yapi 应该是最合适的了
|
20
EastLord 2019-06-05 12:29:44 +08:00
swagger
|
21
mylxsw 2019-06-05 12:31:13 +08:00 via Android
推荐用 wizard,内网部署 https://github.com/mylxsw/wizard
|
22
anankun OP 用 swagger 写,代码侵入感觉太多了。单后端看还行,前端看有些实体的参数确定不了
|
23
brust 2019-06-05 12:31:48 +08:00
swagger
jsonapi |
24
TommyLemon 2019-06-05 12:31:57 +08:00 1
比 Postman,Swagger,EOLinker,Rap,apidoc 等一堆工具在基础的文档、测试方面要强大易用很多。 自动化接口管理工具,自动生成代码、自动静态检查、自动化回归测试、自动生成文档与注释等。 * 自动生成接口文档,清晰可读永远最新 * 自动校验与格式化,支持高亮和收展 * 自动生成各种语言代码,一键下载 * 自动管理与测试接口用例,一键共享 * 自动给请求 JSON 加注释,一键切换 * 自动保存历史请求记录,一键恢复 代码已开源,可以点 Star 支持下哦 ^_^ github.com/TommyLemon/APIJSONAuto |
25
TommyLemon 2019-06-05 12:32:55 +08:00
@TommyLemon 可以拿源码部署到公司内部,自带测试用例 Demo,有部署文档教程、使用视频教程 等
|
26
TommyLemon 2019-06-05 12:33:28 +08:00
|
27
Macolor21 2019-06-05 12:46:54 +08:00 6
....*** 楼上这个又来了。。真的是
|
28
chendy 2019-06-05 12:57:00 +08:00
我猜会有人来推他的 apijson (虽然 block 了…
|
29
liuxey 2019-06-05 12:59:38 +08:00
现在看到 APIJSON 就烦,不管是作品还是作者!
|
30
salamanderMH 2019-06-05 13:01:32 +08:00
yapi
|
32
coosir 2019-06-05 13:04:40 +08:00
eolinker
|
33
jorneyr 2019-06-05 13:06:49 +08:00
我们使用 yApi
|
34
littlewing 2019-06-05 13:08:38 +08:00
不让上外网为什么就得是离线的?难道你们公司没内网吗
|
35
via 2019-06-05 13:13:05 +08:00
哈哈哈哈,我也觉得那个人会来。
---- 我目前用的是 gitbook cli,但是当 md 文件数量上到 100 多以后,build 一次很慢,大概需要 20 秒。gitbook 还有个好处是可以生成一本 PDF,带封面和目录,可以说很好看了。但是 gitbook cli 目前似乎不维护了,他们家现在主推他们的在线托管服务。 然后用 vscode 来编辑。 |
36
anankun OP @littlewing 有道理,看了回复发现部署个内网 yapi 也是很好。
|
37
xuanbg 2019-06-05 13:38:54 +08:00
直接写 readme.md 里面,gitlab 里面和后端项目在一起。格式是有模板的,http://api.yitu8.cn 可以参考下,顺便提点意见。
|
39
ooee2016 2019-06-05 13:46:33 +08:00
eolinker
|
40
ooee2016 2019-06-05 13:46:52 +08:00
@SirLostWhite 一样
|
42
Takamine 2019-06-05 13:52:58 +08:00 via Android
conference。
|
44
hnbcinfo 2019-06-05 13:58:29 +08:00
项目开发中,做好接口规范,接口名称和请求响应参数描述,利用 Attribute 及注释标注。每次项目编译,利用 Yapi 的开放接口,自动同步已经开发好的接口,包含接口分组、字段注释,接口描述等完整信息。
|
45
ggicci 2019-06-05 13:58:59 +08:00
我喜欢用 apiary。
1. 我把接口文档和源码一起维护; 2. 每次更新文档都提交到 apiary 服务(支持自建,docker 拉一个就好),它会帮你渲染,方便浏览和调试,这个就有点类似 postman 了。 |
46
ggicci 2019-06-05 14:01:00 +08:00
加一句,apiary 是 api-blueprint 的 api 文档编写规范,学习曲线稍会偏高。所以用的人可能不是很多。
|
48
axbx 2019-06-05 14:09:36 +08:00
一个 excel,上传到项目的 SVN。
|
49
TommyLemon 2019-06-05 14:16:08 +08:00
@Macolor21
@liuxey @via 看清楚 APIJSONAuto 和 APIJSON 是两个项目 自动化接口管理工具 ( 300 + Star ) github.com/TommyLemon/APIJSONAuto/ 自动化接口与文档 ORM 库( 6100 + Star ) github.com/APIJSON/APIJSON/ 再说人家提问,回答问题有啥不对?对某些需要的人也是有帮助的。 你们这种宣泄情绪的评论才是违反 V2EX 规则的。 “请尽量让自己的回复能够对别人有帮助” |
50
zaul 2019-06-05 14:16:39 +08:00
小幺鸡
|
51
TommyLemon 2019-06-05 14:17:38 +08:00
@TommyLemon APIJSONAuto-自动化接口管理工具 类似 postman,对代码无任何入侵,也不需要写任何代码哦
|
52
Kenyore 2019-06-05 14:29:57 +08:00
swagger 大法好
|
53
Edsie 2019-06-05 14:58:27 +08:00
能把他屏蔽了吗?
|
54
zgcwkj 2019-06-05 15:04:32 +08:00
口口相传(就是嘴对嘴,一张对一张,传递下去)
|
56
robinlovemaggie 2019-06-05 15:12:48 +08:00
离线版的我觉得不如搞个小本本记下了得了
|
57
ibugeek 2019-06-05 15:19:36 +08:00
现在用 eolinker,感觉比 yapi 好一些
|
58
ifane 2019-06-05 15:22:16 +08:00
apidoc 的没有么
|
59
cctv1005s927 2019-06-05 15:26:48 +08:00
看到 apijson 就烦..
|
60
leafre 2019-06-05 15:29:34 +08:00
swagger
|
61
wocanmei 2019-06-05 15:34:57 +08:00
apijson 木哈哈,eolinker 不错,没人用吗,免费版够用了,界面也挺好看
|
62
jingyulong 2019-06-05 15:39:20 +08:00 via iPhone
说有预感 API JSON 的会来推广的,是想笑死我继承我的花呗吗?
|
64
EmotionV 2019-06-05 16:04:44 +08:00
yapi+swagger
|
66
jaryur 2019-06-05 16:14:24 +08:00 via Android
如果是 HTTP 文档,swagger,eolinker 开源版基本都可以满足,我们现在是基于 dubbo 微服务化,虽然有 dubbo-swagger 但是个人觉得需要开发人员在代码里面编写太多的 api 注释,相当于 api 文档入侵了代码,最近在实现一个基于 javadoc 插件生成 api 文档,然后用静态页面服务器统计集中管理和展示,目的为了解决微服务场景下的 rpc api 文档治理,有过类似实践的可以一起交流下
|
67
feihuxiongdi 2019-06-05 16:17:22 +08:00
@acumen 真!分布式
|
68
karllynn 2019-06-05 16:20:00 +08:00
我们都是直接手写的。。其实也不费事
|
69
mapper 2019-06-05 16:22:51 +08:00
用的 ooi 系统,感觉一般。还是需要人工去配置
|
70
wawehi 2019-06-05 16:30:26 +08:00
后端生成或手写编辑 Markdown 格式,放入内网 GIT 库就完事了?
需要其它格式的都由 md 文件去生成 |
71
chendy 2019-06-05 16:35:37 +08:00
@jaryur 终于看到一个用 javadoc 的了…我们是做了个 annotation-processor,扫 spring-mvc 的注解,读参数返回值生成 adoc
|
72
rockyou12 2019-06-05 16:35:42 +08:00
spring-fox + swagger,很多人觉得注解入侵代码很难看,但本来也只在 controller 层写,而且 controller 的方法基本就一两行,注解多点也不是很碍事啊
|
73
gabon 2019-06-05 16:48:55 +08:00 via Android
SOA 治理工具
|
74
NoKey 2019-06-05 17:00:01 +08:00
请教一下,使用 swagger 的,对于复杂逻辑,或者返回结果需要比较复杂的方式才可以还原的,怎么写的?
我一直用 markdown 写了放 git 里,最近有人说不用 swagger 就落后了,我想,光文档里写一个返回数据如何使用都要写大半也,写到代码注释里,那还不半屏幕的注释啊。。。 |
75
rockyou12 2019-06-05 17:11:03 +08:00
@NoKey 如果只是字段多,嵌套复杂,像 spring-fox 这种是自动扫描类信息的,不需要手写。其它语言基本也有这种 swagger 的自动生成工具
|
76
NoKey 2019-06-05 17:15:29 +08:00
@rockyou12 不是嵌套复杂,是业务复杂,服务器发出去的数据,需要指定的方式才能解析出来,这个指定的方式,需要写半夜文档的样子。。。还有,返回去的字段也是嵌套的,比如 json 里面嵌了一个 String,但是这个 String 实际是个 json,swagger 能解析道这个 String 的结构么?
|
78
rockyou12 2019-06-05 17:27:26 +08:00
@NoKey swagger 其实现在不只是一个文档工具,也是 open api 这个规范的实现,open api 基本只支持 rest api。你接口不符合 rest 那就没办法了ㄟ( ▔, ▔ )ㄏ
|
79
BlBana 2019-06-05 17:30:00 +08:00
话说楼主得是渣康的 ...
|
80
cwx391497 2019-06-05 17:35:26 +08:00
我也是,我这文档都 400 多页了,大范围编辑真的想死
我的想法是用 html 重写,或者把文档做成 chm 格式的,会比较好维护(积重难返.....🤣) |
81
poisedflw 2019-06-05 17:37:33 +08:00
自己部署一套 eolinker
|
82
dif 2019-06-05 17:38:30 +08:00
yapi
|
84
thfurior 2019-06-05 17:55:03 +08:00
别问,问就 doc
|
85
jaryur 2019-06-05 18:13:38 +08:00 via Android
@chendy 生成 javadoc 只是第一步,原生的 javadoc 很不便于查询和展示,我是生成了自定义格式的类 javadoc markdown 文件
|
86
guiling 2019-06-05 18:46:34 +08:00 via Android
yapi
|
87
linvaux 2019-06-05 19:05:00 +08:00 via Android
eolinker
|
89
yoshiyuki 2019-06-05 19:19:42 +08:00
showdoc
|
90
Egfly 2019-06-05 19:21:08 +08:00 via iPhone
Yapi
|
91
sunjiayao 2019-06-05 19:26:38 +08:00
apidoc +1 养成改代码前先改文档注释,再写个自动发布脚本。简直不要太舒服
|
92
zhangtao 2019-06-05 19:43:42 +08:00
yapi +1
|
94
blueorange 2019-06-05 20:33:53 +08:00
swagger-ui.html
|
95
newmind 2019-06-05 20:35:04 +08:00
代码即文档
|
96
wc951 2019-06-05 20:35:25 +08:00 via Android
spring restdoc,文档片段写在单元测试里
|
97
jiangzhuo 2019-06-05 20:58:58 +08:00
swagger
|
98
lygmqkl 2019-06-05 21:54:50 +08:00
postman / showdoc
api 文档而已 搞那么复杂干嘛? 难道你们编程的生活还不够苦难吗? |
100
changwei 2019-06-05 22:42:57 +08:00
|