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

文档

接口

上外网

svn

130 条回复 • 2021-10-12 10:03:22 +08:00

1 2

❮

❯

1

zsdroid

2019-06-05 11:28:29 +08:00

1

yapi

2

acumen

2019-06-05 11:30:21 +08:00 via iPhone

67

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

3

lihongjie0209

2019-06-05 11:31:07 +08:00

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

4

Vegetable

2019-06-05 11:32:30 +08:00

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

5

SirLostWhite

2019-06-05 11:34:49 +08:00

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

6

skiy

2019-06-05 11:36:35 +08:00

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

7

a330202207

2019-06-05 11:37:54 +08:00

showdoc

8

doco

2019-06-05 11:38:21 +08:00

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

9

rexyan

2019-06-05 11:39:29 +08:00

跟着项目走，传 git

10

chinvo

2019-06-05 11:40:37 +08:00 via iPhone

1

openapi + web ui

11

shuipoqian

2019-06-05 11:42:37 +08:00

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

12

kevinlm

2019-06-05 11:46:16 +08:00 via iPhone

9

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

13

razaura

2019-06-05 11:50:15 +08:00

1

swagger

14

introle

2019-06-05 11:51:02 +08:00 via iPhone

1

swagger +1

15

Caballarii

2019-06-05 11:53:21 +08:00

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

16

pengjl

2019-06-05 12:00:38 +08:00

swagger+1

17

zhuwd

2019-06-05 12:13:07 +08:00 via iPhone

yapi

18

cccy0

2019-06-05 12:25:15 +08:00

postman

19

fengxianqi

2019-06-05 12:28:44 +08:00

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

20

EastLord

2019-06-05 12:29:44 +08:00

swagger

21

mylxsw

2019-06-05 12:31:13 +08:00 via Android

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

22

anankun

OP

2019-06-05 12:31:20 +08:00

1

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

23

brust

2019-06-05 12:31:48 +08:00

swagger
jsonapi

24

TommyLemon

2019-06-05 12:31:57 +08:00

1

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

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

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

25

TommyLemon

2019-06-05 12:32:55 +08:00

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

26

TommyLemon

2019-06-05 12:33:28 +08:00

27

Macolor21

2019-06-05 12:46:54 +08:00

6

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

28

chendy

2019-06-05 12:57:00 +08:00

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

29

liuxey

2019-06-05 12:59:38 +08:00

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

30

salamanderMH

2019-06-05 13:01:32 +08:00

yapi

31

rbuli

2019-06-05 13:04:28 +08:00

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

32

coosir

2019-06-05 13:04:40 +08:00

eolinker

33

jorneyr

2019-06-05 13:06:49 +08:00

我们使用 yApi

34

littlewing

2019-06-05 13:08:38 +08:00

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

35

via

2019-06-05 13:13:05 +08:00

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

----

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

然后用 vscode 来编辑。

36

anankun

OP

2019-06-05 13:25:58 +08:00

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

37

xuanbg

2019-06-05 13:38:54 +08:00

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

38

anankun

OP

2019-06-05 13:45:48 +08:00

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

39

ooee2016

2019-06-05 13:46:33 +08:00

eolinker

40

ooee2016

2019-06-05 13:46:52 +08:00

@SirLostWhite 一样

41

anankun

OP

2019-06-05 13:48:55 +08:00

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

42

Takamine

2019-06-05 13:52:58 +08:00 via Android

conference。

43

Takamine

2019-06-05 13:53:28 +08:00 via Android

@Takamine 呸，Confluence 和 Jira。

44

hnbcinfo

2019-06-05 13:58:29 +08:00

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

45

ggicci

2019-06-05 13:58:59 +08:00

我喜欢用 apiary。

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

46

ggicci

2019-06-05 14:01:00 +08:00

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

47

xuanbg

2019-06-05 14:01:40 +08:00

@anankun Pytora 有导航的

48

axbx

2019-06-05 14:09:36 +08:00

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

49

TommyLemon

2019-06-05 14:16:08 +08:00

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

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

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

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

50

zaul

2019-06-05 14:16:39 +08:00

小幺鸡

51

TommyLemon

2019-06-05 14:17:38 +08:00

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

52

Kenyore

2019-06-05 14:29:57 +08:00

swagger 大法好

53

Edsie

2019-06-05 14:58:27 +08:00

能把他屏蔽了吗？

54

zgcwkj

2019-06-05 15:04:32 +08:00

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

55

oliver34

2019-06-05 15:09:21 +08:00

@acumen 优秀

56

robinlovemaggie

2019-06-05 15:12:48 +08:00

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

57

ibugeek

2019-06-05 15:19:36 +08:00

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

58

ifane

2019-06-05 15:22:16 +08:00

apidoc 的没有么

59

cctv1005s927

2019-06-05 15:26:48 +08:00

看到 apijson 就烦..

60

leafre

2019-06-05 15:29:34 +08:00

swagger

61

wocanmei

2019-06-05 15:34:57 +08:00

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

62

jingyulong

2019-06-05 15:39:20 +08:00 via iPhone

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

63

Sadow

2019-06-05 15:46:54 +08:00

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

64

EmotionV

2019-06-05 16:04:44 +08:00

yapi+swagger

65

supuwoerc

2019-06-05 16:11:33 +08:00

@acumen 牛批！

66

jaryur

2019-06-05 16:14:24 +08:00 via Android

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

67

feihuxiongdi

2019-06-05 16:17:22 +08:00

@acumen 真!分布式

68

karllynn

2019-06-05 16:20:00 +08:00

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

69

mapper

2019-06-05 16:22:51 +08:00

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

70

wawehi

2019-06-05 16:30:26 +08:00

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

71

chendy

2019-06-05 16:35:37 +08:00

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

72

rockyou12

2019-06-05 16:35:42 +08:00

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

73

gabon

2019-06-05 16:48:55 +08:00 via Android

SOA 治理工具

74

NoKey

2019-06-05 17:00:01 +08:00

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

75

rockyou12

2019-06-05 17:11:03 +08:00

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

76

NoKey

2019-06-05 17:15:29 +08:00

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

77

rockyou12

2019-06-05 17:24:23 +08:00

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

78

rockyou12

2019-06-05 17:27:26 +08:00

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