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

V2EX = way to explore

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

现在注册

已注册用户请登录

• 请不要在回答技术问题时复制粘贴 AI 生成的内容

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

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

哎。 Fuck

第 1 条附言 · 2017 年 4 月 14 日

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

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

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

API

Markdown

文档

石墨

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

xuanyan

2017 年 4 月 13 日

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

lawmil

2017 年 4 月 13 日

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

ansheng

2017 年 4 月 13 日

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

ansheng

2017 年 4 月 13 日

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

hekunhotmail

2017 年 4 月 13 日

wiki 不谢

2017 年 4 月 13 日

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

AlisaDestiny

2017 年 4 月 13 日

apiview.com

ansheng

2017 年 4 月 13 日

@zi 心疼你三秒。

ansheng

2017 年 4 月 13 日

@AlisaDestiny 贵了点，哈哈。

domty

2017 年 4 月 13 日

confluence

tpsxiong

2017 年 4 月 13 日

https://nei.netease.com/

linoder

2017 年 4 月 13 日

swagger

flyingghost

2017 年 4 月 13 日

www.xiaoyaoji.com
可内网部署

h4x3rotab

2017 年 4 月 13 日

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

lusyoe

2017 年 4 月 13 日 via iPhone

swagger +1

crossoverJie

2017 年 4 月 13 日

有 doc 和 wiki

tkisme

2017 年 4 月 13 日

swagger +1

nashxk

2017 年 4 月 13 日

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

ansheng

2017 年 4 月 13 日

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

ansheng

2017 年 4 月 13 日

@nashxk 没 markdown 真的很痛苦

ansheng

2017 年 4 月 13 日

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

kooze

2017 年 4 月 13 日

口耳相传

zhuf

2017 年 4 月 13 日

apidoc

ansheng

2017 年 4 月 13 日

@kooze 这个吊

snriud

2017 年 4 月 13 日

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

ansheng

2017 年 4 月 13 日

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

wudanyang

2017 年 4 月 13 日

wiki, 不会调格式

gengqiupeng

2017 年 4 月 13 日

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

kaka8wp

2017 年 4 月 13 日

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

ivvei

2017 年 4 月 13 日

没有文档。自己翻代码

izoabr

2017 年 4 月 13 日

口口相传

huigeer

2017 年 4 月 13 日

apidoc + 1

ArthurKing

2017 年 4 月 13 日

swagger +1

huigeer

2017 年 4 月 13 日

更正： ShowDoc

qiu0130

2017 年 4 月 13 日 via Android

难道没有用 tower 的?

klgd

2017 年 4 月 13 日

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

orderc

2017 年 4 月 13 日

gitbook

ansheng

2017 年 4 月 13 日

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

ansheng

2017 年 4 月 13 日

@qiu0130 我司就用，哈哈。

freezhan

2017 年 4 月 13 日

swagger+1

strongcoder

2017 年 4 月 13 日

我司用 word 。。快被气死

Observer42

2017 年 4 月 13 日

swagger

zoffy

2017 年 4 月 13 日

@snriud #25 是这样的

subdued

2017 年 4 月 13 日

我司 API 文档靠口口相传

guodont

2017 年 4 月 13 日

swagger +1
apidoc +1

virusdefender

2017 年 4 月 13 日

口口相传

心有灵犀

xxdd

2017 年 4 月 13 日

口口相传

心有灵犀

(●'◡'●)ﾉ♥

prasanta

2017 年 4 月 13 日

用 mkdocs+git

Ouyangan

2017 年 4 月 13 日

swagger+1

qdpoboy

2017 年 4 月 13 日

喊！呀

Wilon

2017 年 4 月 13 日

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

Vvfan

2017 年 4 月 13 日

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

kisnows

2017 年 4 月 13 日

Word Wiki 有道云 + 口口相传

nextbox

2017 年 4 月 13 日

RAP

imherer

2017 年 4 月 13 日

https://github.com/lord/slate

ydq419453527

2017 年 4 月 13 日

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

Blazings

2017 年 4 月 13 日 via Android

口口相传牛逼

auhah

2017 年 4 月 13 日

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

CTO 特别屌

自己撸了一套 API 网站

还以为是 IT 公司标配

后来几个公司 tmd 全是 word

mfu

2017 年 4 月 13 日

写 WORD 里扔 SVN 上。 T_T

WhoMercy

2017 年 4 月 13 日 via Android

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

nameldk

2017 年 4 月 13 日

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

a412739861

2017 年 4 月 13 日

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

zhleonix

2017 年 4 月 13 日

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

xieweizhi007

2017 年 4 月 13 日 via iPhone

apiary

xieweizhi007

2017 年 4 月 13 日 via iPhone

更正： apiary

G900

2017 年 4 月 13 日

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

V2exUser

2017 年 4 月 13 日

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

orvice

2017 年 4 月 13 日

swagger :)

xu1ming

2017 年 4 月 13 日 via iPhone

我司 google doc

mingyun

2017 年 4 月 13 日

dokuwiki

loveuqian

2017 年 4 月 13 日 via iPhone

就一条 curl 命令

Jakesoft

2017 年 4 月 14 日

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

zzyzxd

2017 年 4 月 14 日

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

jwangkun

2017 年 4 月 14 日 via Android

没人推荐小幺鸡么？

yalanaika

2017 年 4 月 14 日

html - chm

libook

2017 年 4 月 14 日

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