话说你司的 API 文档是如何进行管理的？

V2EX = way to explore

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

现在注册

已注册用户请登录

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

遇到一个尴尬的问题，我司 API 文档都是使用 markdown 来写的，然而是放在项目目录下面的 README.md 中，但是多人人多的时候修改起来就比较麻烦，就想用有没有一种在线的 API 文档管理程序撒的，石墨固然好，好像不支持 Markdown 所以没打算用。

哎。 Fuck

第 1 条附言 · 2017-04-14 09:54:36 +08:00

看了各位的评论，表示API文档还是可以独立部署代表比较好，我可不想把自己程序的API说明丢在别人家。

其次，看了下swagger，感觉UI挺不错，抽时间研究下。

我司下载就是放在仓库下面的README.md中。

API

Markdown

文档

石墨

98 条回复 • 2020-09-04 14:20:56 +08:00

xuanyan

2017-04-13 10:30:53 +08:00

我们用的 mediawiki 搭建的 api 接口词条

lawmil

2017-04-13 10:39:17 +08:00

既然是 md 写的，推荐个系统 docsify 很方便，样式默认 vue 也可以改其他

ansheng

2017-04-13 10:39:24 +08:00

@xuanyan 可以在线修改吗？我想着尽可能就放内网，

ansheng

2017-04-13 10:41:05 +08:00

@lawmil 这个确实很不错，可以考虑。

hekunhotmail

2017-04-13 10:43:05 +08:00

wiki 不谢

2017-04-13 10:46:58 +08:00

我司用 word 。。真的要哭出声来

AlisaDestiny

2017-04-13 10:52:58 +08:00

apiview.com

ansheng

2017-04-13 10:53:54 +08:00

@zi 心疼你三秒。

ansheng

2017-04-13 10:54:35 +08:00

@AlisaDestiny 贵了点，哈哈。

domty

2017-04-13 11:13:29 +08:00

confluence

tpsxiong

2017-04-13 11:15:41 +08:00

https://nei.netease.com/

linoder

2017-04-13 12:24:46 +08:00

swagger

flyingghost

2017-04-13 12:35:43 +08:00

www.xiaoyaoji.com
可内网部署

h4x3rotab

2017-04-13 12:47:55 +08:00

Google 是和源码目录放在一起的 md 文件，同样加入版本管理，代码审查。然后再搭配一个搜索。

lusyoe

2017-04-13 13:08:45 +08:00 via iPhone

swagger +1

crossoverJie

2017-04-13 13:22:00 +08:00

有 doc 和 wiki

tkisme

2017-04-13 13:22:46 +08:00

swagger +1

nashxk

2017-04-13 13:36:07 +08:00

confluence 。不过没用 markdown ，而且改版的时候更新也不是很及时。。

ansheng

2017-04-13 14:08:13 +08:00

@flyingghost 表示打不开，就是需要内网部署的。

ansheng

2017-04-13 14:08:28 +08:00

@nashxk 没 markdown 真的很痛苦

ansheng

2017-04-13 14:08:50 +08:00

@tkisme2013
@lusyoe
@linoder
考虑下午玩玩看。

kooze

2017-04-13 14:10:41 +08:00

口耳相传

zhuf

2017-04-13 14:11:36 +08:00

apidoc

ansheng

2017-04-13 14:15:45 +08:00

@kooze 这个吊

snriud

2017-04-13 14:36:41 +08:00

最开始是写在 wiki 里，认认真真，完完整整，慢慢地就不维护了，有人要接口文档的话就用 postman 请求一次，截图发给谁。。。

ansheng

2017-04-13 14:39:09 +08:00

@snriud 我也在用 postman ，因为老大没买这个东，所以还不能做到团队公用，

wudanyang

2017-04-13 14:51:00 +08:00

wiki, 不会调格式

gengqiupeng

2017-04-13 14:54:18 +08:00

小幺鸡在线文档。不过不是用 markdown 写的

kaka8wp

2017-04-13 15:06:39 +08:00

有部分文档但基本上不是最新的，最新的也是靠口耳相传

ivvei

2017-04-13 15:12:31 +08:00

没有文档。自己翻代码

izoabr

2017-04-13 15:18:04 +08:00

口口相传

huigeer

2017-04-13 15:24:25 +08:00

apidoc + 1

ArthurKing

2017-04-13 15:26:06 +08:00

swagger +1

huigeer

2017-04-13 15:27:06 +08:00

更正： ShowDoc

qiu0130

2017-04-13 15:38:56 +08:00 via Android

难道没有用 tower 的?

klgd

2017-04-13 15:45:12 +08:00

showdoc + apidoc
showdoc 是前人用的， coding+编辑维护不是方便，后来用 apidoc ，注释直接写在 code 里，然后命令生成，虽然注释在编写时也不是太方便，但感觉对 coding 和维护好一点儿

orderc

2017-04-13 16:08:00 +08:00

gitbook

ansheng

2017-04-13 16:14:40 +08:00

@klgd View 里面加注释确实会给后人一个更方便理解，但我司的风格不适合

ansheng

2017-04-13 16:15:01 +08:00

@qiu0130 我司就用，哈哈。

freezhan

2017-04-13 16:19:46 +08:00

swagger+1

strongcoder

2017-04-13 16:30:46 +08:00

我司用 word 。。快被气死

Observer42

2017-04-13 16:38:03 +08:00

swagger

zoffy

2017-04-13 16:39:54 +08:00

@snriud #25 是这样的

subdued

2017-04-13 16:42:07 +08:00

我司 API 文档靠口口相传

guodont

2017-04-13 16:46:31 +08:00

swagger +1
apidoc +1

virusdefender

2017-04-13 16:50:57 +08:00

口口相传

心有灵犀

xxdd

2017-04-13 16:56:46 +08:00

口口相传

心有灵犀

(●'◡'●)ﾉ♥

prasanta

2017-04-13 17:02:46 +08:00

用 mkdocs+git

Ouyangan

2017-04-13 17:17:10 +08:00

swagger+1

qdpoboy

2017-04-13 17:36:00 +08:00

喊！呀

Wilon

2017-04-13 17:36:47 +08:00

@izoabr 上班着，要被你的答案笑死了，虽然我们也是口口相传

Vvfan

2017-04-13 17:37:11 +08:00

看来不止我们用 word /(ㄒoㄒ)/~~

kisnows

2017-04-13 17:54:17 +08:00

Word Wiki 有道云 + 口口相传

nextbox

2017-04-13 17:56:12 +08:00

RAP

imherer

2017-04-13 18:22:43 +08:00

https://github.com/lord/slate

ydq419453527

2017-04-13 18:29:33 +08:00

@zi @strongcoder @Vvfan txt 的默默路过 =。=

Blazings

2017-04-13 18:30:13 +08:00 via Android

口口相传牛逼

auhah

2017-04-13 18:31:49 +08:00

想起了前前前公司，我刚工作的时候

CTO 特别屌

自己撸了一套 API 网站

还以为是 IT 公司标配

后来几个公司 tmd 全是 word

mfu

2017-04-13 18:32:03 +08:00

写 WORD 里扔 SVN 上。 T_T

WhoMercy

2017-04-13 18:43:24 +08:00 via Android

遇到过 word 生成 html 扔内网服务器，给个固定网址的……

nameldk

2017-04-13 19:53:28 +08:00

文档是写在代码里，然后有专门处理程序会把代码的文档提取出来，生成 api 文档，同时生成测试工具:)

a412739861

2017-04-13 20:04:35 +08:00

@kooze #22 还不错了，我们是代码讲那过去的故事……

zhleonix

2017-04-13 20:09:19 +08:00

用 Swagger 或者 RAML 写 YAML 规范，自动产生文档和代码。

xieweizhi007

2017-04-13 21:53:05 +08:00 via iPhone

apiary

xieweizhi007

2017-04-13 21:53:37 +08:00 via iPhone

更正： apiary

G900

2017-04-13 22:02:52 +08:00

GitLab ，和代码分开，做一个单独的 doc 库，用 markdown 写，管理方便

V2exUser

2017-04-13 22:07:01 +08:00

@subdued 听过口耳相传，实在想不出贵司的口口相传是怎样的风景。

orvice

2017-04-13 22:50:07 +08:00

swagger :)

xu1ming

2017-04-13 22:53:11 +08:00 via iPhone

我司 google doc

mingyun

2017-04-13 23:10:52 +08:00

dokuwiki

loveuqian

2017-04-13 23:36:45 +08:00 via iPhone

就一条 curl 命令

Jakesoft

2017-04-14 00:50:49 +08:00

竟然没有 sphinx ，专业文档编写 100 年

zzyzxd

2017-04-14 07:44:49 +08:00

前公司是把 git 目录 mount 到一个 MkDocs 的 container 里……

jwangkun

2017-04-14 07:46:05 +08:00 via Android

没人推荐小幺鸡么？

yalanaika

2017-04-14 08:03:36 +08:00

html - chm

libook

2017-04-14 08:06:07 +08:00

个人觉得 API 文档维护的最大问题是忘记维护，或者有时候赶时间就懒得维护，所以个人倾向于将 API 文档与代码放在一起。
我们是 JS 全栈， JS 有一套 JSDoc 标准，适用于非 API 场景的文档编写，依照这个标准，有一个 APIDoc 工具，可以用类似 JSDoc 的方式在代码中用注释编写 API 文档，但是在实际应用过程中感觉不适合我们的应用场景，所以自己写了一个 URIDoc https://www.npmjs.com/package/uridoc
目前还是 v1 的初级阶段，欢迎 Fork 和 PullRequest