你们团队都是怎么管理 API 文档的

API

文档

wiki

doc

102 条回复 2019-10-30 18:58:30 +08:00

1 2

1

yxzblue

2017-02-16 08:38:17 +08:00

Swagger

2

kancloud

2017-02-16 08:43:13 +08:00

用看云可以支持 api 文档在线调试

3

coldmn3

2017-02-16 08:58:04 +08:00

用的 Confluence, 感觉还行吧，同求推荐。

4

linkoubian

2017-02-16 09:00:31 +08:00

@coldmn3 同样是 Confluence

5

loadsome

2017-02-16 09:03:44 +08:00 via iPhone

小幺鸡

6

Felldeadbird

2017-02-16 09:07:19 +08:00

写工具反射得出 API 文档

7

jimyan

OP

2017-02-16 09:14:43 +08:00 via Android

@Felldeadbird 我们是先文档，除了 API 文档，还有设计文档等

8

liyj144

2017-02-16 09:24:44 +08:00

参考： t/309716#reply9

9

daben1990

2017-02-16 09:27:04 +08:00

https://github.com/fyddaben/lettuce 我们用的 API Blueprint 语法，然后起了个 mock server ，

10

SourceMan

2017-02-16 09:27:26 +08:00

7

口头传述

11

thanksir

2017-02-16 09:27:26 +08:00

推荐 showdoc ，这个还不错的

12

chipmuck

2017-02-16 09:28:01 +08:00

通过 gitlab 传 md....

13

StevenTong

2017-02-16 09:28:27 +08:00

swagger +1

14

lifesimple

2017-02-16 09:29:54 +08:00

swagger +2

15

Abigale

2017-02-16 09:31:14 +08:00

没有。

16

awolfly9

2017-02-16 09:31:16 +08:00

天啦，还有 API 文档,没听说过

17

superpeaser

2017-02-16 09:34:02 +08:00 via iPhone

Confluence +1

18

lijinma

2017-02-16 09:35:07 +08:00

raml

19

Asan

2017-02-16 09:37:05 +08:00

wiki

20

wawehi

2017-02-16 09:37:30 +08:00

gogs 建个项目传 .md 上去

21

liyu001989

2017-02-16 09:38:37 +08:00

apidoc http://apidocjs.com/

22

odirus

2017-02-16 09:39:26 +08:00

尝试过很多，不过现在都转入了 doc ，模板建立好之后，还是挺方便的。

23

tjxiter

2017-02-16 09:41:58 +08:00

没有 API 文档。。。

24

PICKSOMETHING

2017-02-16 09:47:54 +08:00

quip

25

mcfog

2017-02-16 09:54:51 +08:00

内嵌在代码中，验证参数和展示文档调用同一个来源

26

nashxk

2017-02-16 10:11:45 +08:00

confluence ，有个问题是，后来新增的很多字段，都会忘记更新上去。。而且支持 MarkDown 还需要安装插件好像。。

27

solee

2017-02-16 10:15:11 +08:00

apidoc

28

amon

2017-02-16 10:39:15 +08:00

markdown+gitlab

29

ixiaozhi

2017-02-16 10:40:46 +08:00

意念传输

30

wmttom

2017-02-16 10:46:50 +08:00

Swagger +3
代码生成文档，或者文档生成代码，一旦各自独立书写总会产生不一致。

31

jimyan

OP

2017-02-16 10:48:33 +08:00 via Android

@odirus doc 多人编辑和同步很麻烦。当然谷歌 doc 是可以的

32

kaka8wp

2017-02-16 10:56:33 +08:00

swagger+1

33

kenshinhu

2017-02-16 10:57:00 +08:00

1

我这边是在用 node 的 apidoc 。。。。。

34

xwartz

2017-02-16 10:59:20 +08:00

postman

35

settings

2017-02-16 11:01:38 +08:00

Swagger 可以在线调试，根据文档 API 还能反射出静态文档

36

lc4t

2017-02-16 11:08:38 +08:00 via iPhone

swagger+quip

37

MasterC

2017-02-16 11:10:03 +08:00

有道云协作 + markdown

38

zyue

2017-02-16 11:12:37 +08:00

1

使用 wiki 配合 jira 挺好用的

39

klgd

2017-02-16 11:22:29 +08:00

@yxzblue
@StevenTong
@lifesimple
@wmttom
@kaka8wp
@settings
@lc4t
请教一下， swagger 有版本间的比较吗？

40

lshero

2017-02-16 11:22:58 +08:00

Confluence 编辑文档浏览器天天卡死

41

zhuf

2017-02-16 11:28:56 +08:00

swagger+1

42

mckelvin

2017-02-16 11:53:46 +08:00

https://apiblueprint.org/ 用 atom 加插件写类似 Markdown 的语法，用 Aglio 渲染成 html 文档, 顺手用 Drakov 生成 mock server 方便前后端分离开发。

43

kankana

2017-02-16 12:22:52 +08:00 via iPhone

apizza.cc 用的是这个。 postman 后直接文档

/td>

44

caixiexin

2017-02-16 12:26:24 +08:00 via Android

用 swagger 可以保持接口跟文档同时更新，但是如果用接口生成文档的方式，源代码会有很多原来放在文档里的说明信息。
不管哪种方式，写文档的工作是省不掉的

45

firstfire

2017-02-16 12:40:36 +08:00

代码里用 Javadoc
API 文档用 Markdown 写用 SVN 管理版本

46

run2

2017-02-16 12:47:47 +08:00

OpenAPI / Swagger

47

argon33

2017-02-16 13:02:25 +08:00

文档的维护太难了。。。放在代码库里？

48

settings

2017-02-16 13:45:40 +08:00

@klgd 版本间的比较指的是文档更新后的对比吗？

49

geeksu

2017-02-16 13:46:28 +08:00

我们的 API 没有文档。。

50

AJian

2017-02-16 14:29:14 +08:00

用过 RAP

51

Ixizi

2017-02-16 14:39:51 +08:00

目前在用 RAP 虽然不喜欢 java

52

Jackeriss

2017-02-16 14:50:23 +08:00 via iPhone

@ixiaozhi 神圣的 F2 连着我们的思想

53

loveskyforever

2017-02-16 14:54:50 +08:00

用的是 SBDoc ，可以内网测试， mock 数据，自动生成文档，干净无插件 http://123.57.77.6

54

Ypoem

2017-02-16 15:04:02 +08:00

支持下

55

yy1300326388

2017-02-16 16:35:38 +08:00

postmant

56

zorui

2017-02-16 16:49:24 +08:00

swagger +1

57

zorui

2017-02-16 16:50:19 +08:00

swagger + asciidoc

58

v4ex4b

2017-02-16 16:59:30 +08:00

@SourceMan \()/

59

irory

2017-02-16 17:59:50 +08:00

推荐自动生成文档, 比如 PY 的 sphinx ， api 更新方便维护，一键生成也方便。

60

ivanyin

2017-02-16 18:44:07 +08:00

用 RAP

61

codeyung

2017-02-16 19:04:04 +08:00

Confluence

62

freestyle

2017-02-16 19:50:09 +08:00 via iPhone

API 的话 Swagger 搭一个本地服务器然后用 yaml 写文档就行了，自动渲染高亮

63

jimyan

OP

2017-02-16 20:28:01 +08:00

@freestyle 这个只能是 java 吗

64

lgn21st

2017-02-16 20:40:46 +08:00

居然没有 https://github.com/lord/slate

65

freestyle

2017-02-16 20:52:58 +08:00

@jimyan 任何语言 API 是 json 构建的就行官网:http://swagger.io/swagger-ui/ github:https://github.com/swagger-api/swagger-ui clone 下来, 随便搞个简单 http 服务器, dist 目录作为作为 root 目录就可以跑起来也可以后面小修改下加登录才能查看语法规范在这里 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md

66

klgd

2017-02-16 21:16:20 +08:00

@settings 嗯是的可以对比吗？

67

Monstercat

2017-02-16 21:18:43 +08:00

Github Private Repo 放 MD...

68

lzjamao

2017-02-16 21:23:23 +08:00

无

69

abirdcanfly

2017-02-16 22:42:01 +08:00

我是业务部门的, 对接的 IT 部门每用一次 API 让我们在对接门户导一次 <<<吐槽

70

langjiyuan

2017-02-16 22:55:42 +08:00

意念传输 2333

71

FurN1

2017-02-16 23:14:18 +08:00

楼主附言的背后应该是一张面无表情的脸

72

romennts

2017-02-17 00:32:35 +08:00

@kancloud 我在用看云 Hhhh

73

cxbig

2017-02-17 02:00:55 +08:00

公司用 Atlassian 的产品
所以需求和设计文档一般都是 Confluence 做描述， PSD 类设计文件用 Google Drive 共享。
关于 API 文档，如 PHP 项目：公司要求每个 attribute 和 method 必须写清楚 PHP Doc ，大家都用 PhpStorm ，一个类有什么东西、怎么用一目了然。

74

msg7086

2017-02-17 03:34:55 +08:00

意念传输，这个总结得很好……

75

whalegia

2017-02-17 05:25:27 +08:00

OneNote + Swagger

76

rashawn

2017-02-17 06:43:37 +08:00 via iPhone

通过代码生成缺点是代码里注释有点多…

77

Cbdy

2017-02-17 07:43:51 +08:00 via Android

根据代码注释生成文档（ javadoc ）+ 根据 api 接口使用 springfox 的工具生成 adoc

只要写好代码，文档都是自动生成的

78

winglight2016

2017-02-17 09:25:52 +08:00

意念传输就服这个，能传授吗？

79

juice

2017-02-17 09:29:46 +08:00

postman ， swagger

80

Yuansir

2017-02-17 09:30:06 +08:00

居然没有 gitbook

81

zhangliang605

2017-02-17 09:54:55 +08:00

Confluence 。
是我们是一个 1200+人的团队，面临开发，测试，产品经理，项目经理，运营，商务等等各个部门的协作。 Confluence 能跟公司的通信录系统，邮箱系统对接。当关注的文档发生变化时，立即发送邮件给相关同事。同时， Confluence 支持各种插件，富文本编辑，代码高亮，评论，备注等等功能一应俱全。

82

antowa

2017-02-17 10:20:02 +08:00

我司使用意念传输。精神授权。

83

settings

2017-02-17 11:42:09 +08:00

@klgd 默认不支持，可以反射 markdown ，我们是用 swagger api 反射 markdown ，再把 markdown 提交 git ，通过 gollum 展示 wiki 。

生成 markdown 的脚本： https://github.com/ZhangBohan/swagger_to_markdown

84

keepcleargas

2017-02-17 11:45:38 +08:00

slate + git

85

wjh3936

2017-02-17 12:31:09 +08:00

文档？看代码 [冷漠脸]

86

sumuu

2017-02-17 12:59:47 +08:00

Swagger + Google Drive

87

klgd

2017-02-17 13:34:23 +08:00

@settings 呃~
要这么麻烦哦

88

billyu

2017-02-17 13:35:58 +08:00

我用的 EasyAPI

89

caotian

2017-02-17 15:36:32 +08:00

用的 http://daux.io/，还不错

90

settings

2017-02-17 16:35:52 +08:00

@klgd 恩，是的 :D

91

Hypn0s

2017-02-17 17:14:04 +08:00

Confluence+1

92

flowerwrong

2017-02-17 17:15:10 +08:00 via iPhone

口口想传

93

sampeng

2017-02-17 19:48:17 +08:00

api 是什么东西？可以吃吗？

94

airingursb

2017-02-19 14:01:53 +08:00 via iPhone

rap

95

962680038

2017-02-20 10:00:42 +08:00

SBDoc 不错啊，楼主可以去了解下，操作很简洁，效果很好，链接： http://123.57.77.6/

96

dozer47528

2017-02-20 10:48:44 +08:00

想不收费自己搭建的话，可以使用 https://apiblueprint.org/
它本身提供云服务，但也可以自己搭建。写文档就是写 markdown ， github 也认这种格式。

然后开源社区已经做好了各种工具，包括把 apiblueprint 格式生成 html ， apiblueprint 生成 mock server 等等，非常方便。
我做了个 docker 镜像，只要提供你们写文档的 git 仓库，就可以一键搭建。包含文档服务器， mock server 和 hook api （文档更新的时候自动更新相关内容）
https://github.com/dozer47528/api-blueprint-docker

另外，你可能会需要对静态网站做 oauth2 认证功能，可以利用这个东西： https://github.com/bitly/oauth2_proxy

可以配置邮箱白名单，这样只有你们公司的人能访问了。