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

yapi

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

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

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

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

showdoc

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

跟着项目走，传 git

openapi + web ui

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

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

swagger

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

swagger+1

yapi

postman

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

swagger

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

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

swagger
jsonapi

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

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

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

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

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

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

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

yapi

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

eolinker

我们使用 yApi

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

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

----

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

然后用 vscode 来编辑。

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

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

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

eolinker

@SirLostWhite 一样

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

conference。

@Takamine 呸，Confluence 和 Jira。

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

我喜欢用 apiary。

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

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

@anankun Pytora 有导航的

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

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

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

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

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

小幺鸡

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

swagger 大法好

能把他屏蔽了吗？

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

@acumen 优秀

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

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

apidoc 的没有么

看到 apijson 就烦..

swagger

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

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

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

yapi+swagger

@acumen 牛批！

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

@acumen 真!分布式

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

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

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

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

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

SOA 治理工具

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

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

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

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

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

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

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

自己部署一套 eolinker

yapi

@rockyou12 谢谢

别问，问就 doc

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

yapi

eolinker

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

showdoc

Yapi

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

yapi +1

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

swagger-ui.html

代码即文档

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

swagger

postman / showdoc

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

@acumen 你牛逼

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