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

[anankun]

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

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

[zsdroid]

yapi

[acumen]

口口相传，分布式存储在脑海

[lihongjie0209]

既然是后端, 直接看代码.

[Vegetable]

现在是 yapi,以前也尝试过 gitbook 来做,怪不方便的.

[SirLostWhite]

一开始用的 apizza
后来转用 eolinker 还挺好用的

[skiy]

API 文档？管理平台好多。我在用的是 mindoc。

[a330202207]

showdoc

[doco]

之前是 showDoc, 现在是 YAPI, 然而后台都不喜欢写接口文档

[rexyan]

跟着项目走，传 git

[chinvo]

openapi + web ui

[shuipoqian]

yapi , 同时后端集成了 springfox 生成 swagger 文档, 然后 swagger 的文档可以直接导入到 yapi

[kevinlm]

一杯茶，一盒烟，一个参数传一天

[razaura]

swagger

[introle]

swagger +1

[Caballarii]

肯定 swagger 啊，能直接试比看文档强多了好吧

[pengjl]

swagger+1

[zhuwd]

yapi

[cccy0]

postman

[fengxianqi]

内网部署 yapi 应该是最合适的了

[EastLord]

swagger

[mylxsw]

推荐用 wizard，内网部署 https://github.com/mylxsw/wizard

[anankun]

用 swagger 写，代码侵入感觉太多了。单后端看还行，前端看有些实体的参数确定不了

[brust]

swagger
jsonapi

[TommyLemon]

比 Postman，Swagger，EOLinker，Rap，apidoc 等一堆工具在基础的文档、测试方面要强大易用很多。

自动化接口管理工具，自动生成代码、自动静态检查、自动化回归测试、自动生成文档与注释等。
* 自动生成接口文档，清晰可读永远最新
* 自动校验与格式化，支持高亮和收展
* 自动生成各种语言代码，一键下载
* 自动管理与测试接口用例，一键共享
* 自动给请求 JSON 加注释，一键切换
* 自动保存历史请求记录，一键恢复

代码已开源，可以点 Star 支持下哦 ^_^
github.com/TommyLemon/APIJSONAuto

[TommyLemon]

@TommyLemon 可以拿源码部署到公司内部，自带测试用例 Demo，有部署文档教程、使用视频教程 等

[TommyLemon]

[Macolor21]

....*** 楼上这个又来了。。真的是

[chendy]

我猜会有人来推他的 apijson （虽然 block 了…

[liuxey]

现在看到 APIJSON 就烦，不管是作品还是作者！

[salamanderMH]

yapi

[rbuli]

@acumen 哈哈哈哈，秀儿是你吗

[coosir]

eolinker

[jorneyr]

我们使用 yApi

[littlewing]

不让上外网为什么就得是离线的？难道你们公司没内网吗

[via]

哈哈哈哈，我也觉得那个人会来。

----

我目前用的是 gitbook cli，但是当 md 文件数量上到 100 多以后，build 一次很慢，大概需要 20 秒。gitbook 还有个好处是可以生成一本 PDF，带封面和目录，可以说很好看了。但是 gitbook cli 目前似乎不维护了，他们家现在主推他们的在线托管服务。

然后用 vscode 来编辑。

[anankun]

@littlewing 有道理，看了回复发现部署个内网 yapi 也是很好。

[xuanbg]

直接写 readme.md 里面，gitlab 里面和后端项目在一起。格式是有模板的，http://api.yitu8.cn 可以参考下，顺便提点意见。

[anankun]

@via VS code 确实可以，几万个字符也不带卡顿的，typora 下拉都是一顿一顿的

[ooee2016]

eolinker

[ooee2016]

@SirLostWhite 一样

[anankun]

@xuanbg 目录能固定在页面上就好了

[Takamine]

conference。

[Takamine]

@Takamine 呸，Confluence 和 Jira。

[hnbcinfo]

项目开发中，做好接口规范，接口名称和请求响应参数描述，利用 Attribute 及注释标注。每次项目编译，利用 Yapi 的开放接口，自动同步已经开发好的接口，包含接口分组、字段注释，接口描述等完整信息。

[ggicci]

我喜欢用 apiary。

1. 我把接口文档和源码一起维护；
2. 每次更新文档都提交到 apiary 服务（支持自建，docker 拉一个就好），它会帮你渲染，方便浏览和调试，这个就有点类似 postman 了。

[ggicci]

加一句，apiary 是 api-blueprint 的 api 文档编写规范，学习曲线稍会偏高。所以用的人可能不是很多。

[xuanbg]

@anankun Pytora 有导航的

[axbx]

一个 excel,上传到项目的 SVN。

[TommyLemon]

@Macolor21
@liuxey
@via
看清楚 APIJSONAuto 和 APIJSON 是两个项目

自动化接口管理工具 （ 300 + Star ）
github.com/TommyLemon/APIJSONAuto/

自动化接口与文档 ORM 库（ 6100 + Star ）
github.com/APIJSON/APIJSON/

再说人家提问，回答问题有啥不对？对某些需要的人也是有帮助的。
你们这种宣泄情绪的评论才是违反 V2EX 规则的。
“请尽量让自己的回复能够对别人有帮助”

[zaul]

小幺鸡

[TommyLemon]

@TommyLemon APIJSONAuto-自动化接口管理工具 类似 postman，对代码无任何入侵，也不需要写任何代码哦

[Kenyore]

swagger 大法好

[Edsie]

能把他屏蔽了吗？

[zgcwkj]

口口相传（就是嘴对嘴，一张对一张，传递下去）

[oliver34]

@acumen 优秀

[robinlovemaggie]

离线版的我觉得不如搞个小本本记下了得了

[ibugeek]

现在用 eolinker，感觉比 yapi 好一些

[ifane]

apidoc 的没有么

[cctv1005s927]

看到 apijson 就烦..

[leafre]

swagger

[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 格式的,会比较好维护(积重难返.....🤣)

[poisedflw]

自己部署一套 eolinker

[dif]

yapi

[NoKey]

@rockyou12 谢谢

[thfurior]

别问，问就 doc

[jaryur]

@chendy 生成 javadoc 只是第一步，原生的 javadoc 很不便于查询和展示，我是生成了自定义格式的类 javadoc markdown 文件

[guiling]

yapi

[linvaux]

eolinker

[chendy]

@jaryur 是开源的吗？想参考一下

[yoshiyuki]

showdoc

[Egfly]

Yapi

[sunjiayao]

apidoc +1 养成改代码前先改文档注释，再写个自动发布脚本。简直不要太舒服

[zhangtao]

yapi +1

[jaryur]

@chendy 目前还在开发中，用的是 docsify 做展示

[blueorange]

swagger-ui.html

[newmind]

代码即文档

[wc951]

spring restdoc，文档片段写在单元测试里

[jiangzhuo]

swagger

[lygmqkl]

postman / showdoc

api 文档而已 搞那么复杂干嘛？ 难道你们编程的生活还不够苦难吗？

[kindle958]

@acumen 你牛逼

[changwei]

@liuxey
@TommyLemon
@Macolor21
@liuxey
@via
萌新弱弱地问一句，他的 api 文档项目有什么问题吗？开源免费为什么要喷啊 = =