大家接口文档都是怎么管理的。

[anankun]

我是公司后端开发，目前公司接口使用的是 word 记录，在 svn 上 管理的。 现在一个工程的接口文档到了快 200 页，电脑编辑保存下文档真是卡的不行。

想问下大家都是管理接口文档的，最好是离线的，公司不允许接口文档上外网。

[wocanmei]

apijson 木哈哈，eolinker 不错，没人用吗，免费版够用了，界面也挺好看

[jingyulong]

说有预感 API JSON 的会来推广的，是想笑死我继承我的花呗吗？

[Sadow]

@acumen 分布式储存在脑海可太秀了哈哈哈哈哈哈哈哈哈哈

[EmotionV]

yapi+swagger

[supuwoerc]

@acumen 牛批！

[jaryur]

如果是 HTTP 文档，swagger，eolinker 开源版基本都可以满足，我们现在是基于 dubbo 微服务化，虽然有 dubbo-swagger 但是个人觉得需要开发人员在代码里面编写太多的 api 注释，相当于 api 文档入侵了代码，最近在实现一个基于 javadoc 插件生成 api 文档，然后用静态页面服务器统计集中管理和展示，目的为了解决微服务场景下的 rpc api 文档治理，有过类似实践的可以一起交流下

[feihuxiongdi]

@acumen 真!分布式

[karllynn]

我们都是直接手写的。。其实也不费事

[mapper]

用的 ooi 系统，感觉一般。还是需要人工去配置

[wawehi]

后端生成或手写编辑 Markdown 格式，放入内网 GIT 库就完事了？
需要其它格式的都由 md 文件去生成

[chendy]

@jaryur 终于看到一个用 javadoc 的了…我们是做了个 annotation-processor，扫 spring-mvc 的注解，读参数返回值生成 adoc

[rockyou12]

spring-fox + swagger，很多人觉得注解入侵代码很难看，但本来也只在 controller 层写，而且 controller 的方法基本就一两行，注解多点也不是很碍事啊

[gabon]

SOA 治理工具

[NoKey]

请教一下，使用 swagger 的，对于复杂逻辑，或者返回结果需要比较复杂的方式才可以还原的，怎么写的？
我一直用 markdown 写了放 git 里，最近有人说不用 swagger 就落后了，我想，光文档里写一个返回数据如何使用都要写大半也，写到代码注释里，那还不半屏幕的注释啊。。。

[rockyou12]

@NoKey 如果只是字段多，嵌套复杂，像 spring-fox 这种是自动扫描类信息的，不需要手写。其它语言基本也有这种 swagger 的自动生成工具

[NoKey]

@rockyou12 不是嵌套复杂，是业务复杂，服务器发出去的数据，需要指定的方式才能解析出来，这个指定的方式，需要写半夜文档的样子。。。还有，返回去的字段也是嵌套的，比如 json 里面嵌了一个 String，但是这个 String 实际是个 json，swagger 能解析道这个 String 的结构么？

[rockyou12]

@NoKey 你这种除了手写没有其它解决办法

[rockyou12]

@NoKey swagger 其实现在不只是一个文档工具，也是 open api 这个规范的实现，open api 基本只支持 rest api。你接口不符合 rest 那就没办法了ㄟ( ▔, ▔ )ㄏ

[BlBana]

话说楼主得是渣康的 ...

[cwx391497]

我也是,我这文档都 400 多页了,大范围编辑真的想死
我的想法是用 html 重写,或者把文档做成 chm 格式的,会比较好维护(积重难返.....🤣)