V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
anankun
V2EX  ›  程序员

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

  •  2
     
  •   anankun · 2019-06-05 11:21:07 +08:00 · 19131 次点击
    这是一个创建于 1996 天前的主题,其中的信息可能已经有所发展或是发生改变。

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

    想问下大家都是管理接口文档的,最好是离线的,公司不允许接口文档上外网。
    
    130 条回复    2021-10-12 10:03:22 +08:00
    1  2  
    zsdroid
        1
    zsdroid  
       2019-06-05 11:28:29 +08:00   ❤️ 1
    yapi
    acumen
        2
    acumen  
       2019-06-05 11:30:21 +08:00 via iPhone   ❤️ 67
    口口相传,分布式存储在脑海
    lihongjie0209
        3
    lihongjie0209  
       2019-06-05 11:31:07 +08:00
    既然是后端, 直接看代码.
    Vegetable
        4
    Vegetable  
       2019-06-05 11:32:30 +08:00
    现在是 yapi,以前也尝试过 gitbook 来做,怪不方便的.
    SirLostWhite
        5
    SirLostWhite  
       2019-06-05 11:34:49 +08:00
    一开始用的 apizza
    后来转用 eolinker 还挺好用的
    skiy
        6
    skiy  
       2019-06-05 11:36:35 +08:00
    API 文档?管理平台好多。我在用的是 mindoc。
    a330202207
        7
    a330202207  
       2019-06-05 11:37:54 +08:00
    showdoc
    doco
        8
    doco  
       2019-06-05 11:38:21 +08:00
    之前是 showDoc, 现在是 YAPI, 然而后台都不喜欢写接口文档
    rexyan
        9
    rexyan  
       2019-06-05 11:39:29 +08:00
    跟着项目走,传 git
    chinvo
        10
    chinvo  
       2019-06-05 11:40:37 +08:00 via iPhone   ❤️ 1
    openapi + web ui
    shuipoqian
        11
    shuipoqian  
       2019-06-05 11:42:37 +08:00
    yapi , 同时后端集成了 springfox 生成 swagger 文档, 然后 swagger 的文档可以直接导入到 yapi
    kevinlm
        12
    kevinlm  
       2019-06-05 11:46:16 +08:00 via iPhone   ❤️ 9
    一杯茶,一盒烟,一个参数传一天
    razaura
        13
    razaura  
       2019-06-05 11:50:15 +08:00   ❤️ 1
    swagger
    introle
        14
    introle  
       2019-06-05 11:51:02 +08:00 via iPhone   ❤️ 1
    swagger +1
    Caballarii
        15
    Caballarii  
       2019-06-05 11:53:21 +08:00
    肯定 swagger 啊,能直接试比看文档强多了好吧
    pengjl
        16
    pengjl  
       2019-06-05 12:00:38 +08:00
    swagger+1
    zhuwd
        17
    zhuwd  
       2019-06-05 12:13:07 +08:00 via iPhone
    yapi
    cccy0
        18
    cccy0  
       2019-06-05 12:25:15 +08:00
    postman
    fengxianqi
        19
    fengxianqi  
       2019-06-05 12:28:44 +08:00
    内网部署 yapi 应该是最合适的了
    EastLord
        20
    EastLord  
       2019-06-05 12:29:44 +08:00
    swagger
    mylxsw
        21
    mylxsw  
       2019-06-05 12:31:13 +08:00 via Android
    推荐用 wizard,内网部署 https://github.com/mylxsw/wizard
    anankun
        22
    anankun  
    OP
       2019-06-05 12:31:20 +08:00   ❤️ 1
    用 swagger 写,代码侵入感觉太多了。单后端看还行,前端看有些实体的参数确定不了
    brust
        23
    brust  
       2019-06-05 12:31:48 +08:00
    swagger
    jsonapi
    TommyLemon
        24
    TommyLemon  
       2019-06-05 12:31:57 +08:00   ❤️ 1

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

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

    代码已开源,可以点 Star 支持下哦 ^_^
    github.com/TommyLemon/APIJSONAuto
    TommyLemon
        25
    TommyLemon  
       2019-06-05 12:32:55 +08:00
    @TommyLemon 可以拿源码部署到公司内部,自带测试用例 Demo,有部署文档教程、使用视频教程 等
    TommyLemon
        26
    TommyLemon  
       2019-06-05 12:33:28 +08:00
    Macolor21
        27
    Macolor21  
       2019-06-05 12:46:54 +08:00   ❤️ 6
    ....*** 楼上这个又来了。。真的是
    chendy
        28
    chendy  
       2019-06-05 12:57:00 +08:00
    我猜会有人来推他的 apijson (虽然 block 了…
    liuxey
        29
    liuxey  
       2019-06-05 12:59:38 +08:00
    现在看到 APIJSON 就烦,不管是作品还是作者!
    salamanderMH
        30
    salamanderMH  
       2019-06-05 13:01:32 +08:00
    yapi
    rbuli
        31
    rbuli  
       2019-06-05 13:04:28 +08:00
    @acumen 哈哈哈哈,秀儿是你吗
    coosir
        32
    coosir  
       2019-06-05 13:04:40 +08:00
    eolinker
    jorneyr
        33
    jorneyr  
       2019-06-05 13:06:49 +08:00
    我们使用 yApi
    littlewing
        34
    littlewing  
       2019-06-05 13:08:38 +08:00
    不让上外网为什么就得是离线的?难道你们公司没内网吗
    via
        35
    via  
       2019-06-05 13:13:05 +08:00
    哈哈哈哈,我也觉得那个人会来。

    ----

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

    然后用 vscode 来编辑。
    anankun
        36
    anankun  
    OP
       2019-06-05 13:25:58 +08:00
    @littlewing 有道理,看了回复发现部署个内网 yapi 也是很好。
    xuanbg
        37
    xuanbg  
       2019-06-05 13:38:54 +08:00
    直接写 readme.md 里面,gitlab 里面和后端项目在一起。格式是有模板的,http://api.yitu8.cn 可以参考下,顺便提点意见。
    anankun
        38
    anankun  
    OP
       2019-06-05 13:45:48 +08:00
    @via VS code 确实可以,几万个字符也不带卡顿的,typora 下拉都是一顿一顿的
    ooee2016
        39
    ooee2016  
       2019-06-05 13:46:33 +08:00
    eolinker
    ooee2016
        40
    ooee2016  
       2019-06-05 13:46:52 +08:00
    @SirLostWhite 一样
    anankun
        41
    anankun  
    OP
       2019-06-05 13:48:55 +08:00
    @xuanbg 目录能固定在页面上就好了
    Takamine
        42
    Takamine  
       2019-06-05 13:52:58 +08:00 via Android
    conference。
    Takamine
        43
    Takamine  
       2019-06-05 13:53:28 +08:00 via Android
    @Takamine 呸,Confluence 和 Jira。
    hnbcinfo
        44
    hnbcinfo  
       2019-06-05 13:58:29 +08:00
    项目开发中,做好接口规范,接口名称和请求响应参数描述,利用 Attribute 及注释标注。每次项目编译,利用 Yapi 的开放接口,自动同步已经开发好的接口,包含接口分组、字段注释,接口描述等完整信息。
    ggicci
        45
    ggicci  
       2019-06-05 13:58:59 +08:00
    我喜欢用 apiary。

    1. 我把接口文档和源码一起维护;
    2. 每次更新文档都提交到 apiary 服务(支持自建,docker 拉一个就好),它会帮你渲染,方便浏览和调试,这个就有点类似 postman 了。
    ggicci
        46
    ggicci  
       2019-06-05 14:01:00 +08:00
    加一句,apiary 是 api-blueprint 的 api 文档编写规范,学习曲线稍会偏高。所以用的人可能不是很多。
    xuanbg
        47
    xuanbg  
       2019-06-05 14:01:40 +08:00
    @anankun Pytora 有导航的
    axbx
        48
    axbx  
       2019-06-05 14:09:36 +08:00
    一个 excel,上传到项目的 SVN。
    TommyLemon
        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 规则的。
    “请尽量让自己的回复能够对别人有帮助”
    zaul
        50
    zaul  
       2019-06-05 14:16:39 +08:00
    小幺鸡
    TommyLemon
        51
    TommyLemon  
       2019-06-05 14:17:38 +08:00
    @TommyLemon APIJSONAuto-自动化接口管理工具 类似 postman,对代码无任何入侵,也不需要写任何代码哦
    Kenyore
        52
    Kenyore  
       2019-06-05 14:29:57 +08:00
    swagger 大法好
    Edsie
        53
    Edsie  
       2019-06-05 14:58:27 +08:00
    能把他屏蔽了吗?
    zgcwkj
        54
    zgcwkj  
       2019-06-05 15:04:32 +08:00
    口口相传(就是嘴对嘴,一张对一张,传递下去)
    oliver34
        55
    oliver34  
       2019-06-05 15:09:21 +08:00
    @acumen 优秀
    robinlovemaggie
        56
    robinlovemaggie  
       2019-06-05 15:12:48 +08:00
    离线版的我觉得不如搞个小本本记下了得了
    ibugeek
        57
    ibugeek  
       2019-06-05 15:19:36 +08:00
    现在用 eolinker,感觉比 yapi 好一些
    ifane
        58
    ifane  
       2019-06-05 15:22:16 +08:00
    apidoc 的没有么
    cctv1005s927
        59
    cctv1005s927  
       2019-06-05 15:26:48 +08:00
    看到 apijson 就烦..
    leafre
        60
    leafre  
       2019-06-05 15:29:34 +08:00
    swagger
    wocanmei
        61
    wocanmei  
       2019-06-05 15:34:57 +08:00
    apijson 木哈哈,eolinker 不错,没人用吗,免费版够用了,界面也挺好看
    jingyulong
        62
    jingyulong  
       2019-06-05 15:39:20 +08:00 via iPhone
    说有预感 API JSON 的会来推广的,是想笑死我继承我的花呗吗?
    Sadow
        63
    Sadow  
       2019-06-05 15:46:54 +08:00
    @acumen 分布式储存在脑海可太秀了哈哈哈哈哈哈哈哈哈哈
    EmotionV
        64
    EmotionV  
       2019-06-05 16:04:44 +08:00
    yapi+swagger
    supuwoerc
        65
    supuwoerc  
       2019-06-05 16:11:33 +08:00
    @acumen 牛批!
    jaryur
        66
    jaryur  
       2019-06-05 16:14:24 +08:00 via Android
    如果是 HTTP 文档,swagger,eolinker 开源版基本都可以满足,我们现在是基于 dubbo 微服务化,虽然有 dubbo-swagger 但是个人觉得需要开发人员在代码里面编写太多的 api 注释,相当于 api 文档入侵了代码,最近在实现一个基于 javadoc 插件生成 api 文档,然后用静态页面服务器统计集中管理和展示,目的为了解决微服务场景下的 rpc api 文档治理,有过类似实践的可以一起交流下
    feihuxiongdi
        67
    feihuxiongdi  
       2019-06-05 16:17:22 +08:00
    @acumen 真!分布式
    karllynn
        68
    karllynn  
       2019-06-05 16:20:00 +08:00
    我们都是直接手写的。。其实也不费事
    mapper
        69
    mapper  
       2019-06-05 16:22:51 +08:00
    用的 ooi 系统,感觉一般。还是需要人工去配置
    wawehi
        70
    wawehi  
       2019-06-05 16:30:26 +08:00
    后端生成或手写编辑 Markdown 格式,放入内网 GIT 库就完事了?
    需要其它格式的都由 md 文件去生成
    chendy
        71
    chendy  
       2019-06-05 16:35:37 +08:00
    @jaryur 终于看到一个用 javadoc 的了…我们是做了个 annotation-processor,扫 spring-mvc 的注解,读参数返回值生成 adoc
    rockyou12
        72
    rockyou12  
       2019-06-05 16:35:42 +08:00
    spring-fox + swagger,很多人觉得注解入侵代码很难看,但本来也只在 controller 层写,而且 controller 的方法基本就一两行,注解多点也不是很碍事啊
    gabon
        73
    gabon  
       2019-06-05 16:48:55 +08:00 via Android
    SOA 治理工具
    NoKey
        74
    NoKey  
       2019-06-05 17:00:01 +08:00
    请教一下,使用 swagger 的,对于复杂逻辑,或者返回结果需要比较复杂的方式才可以还原的,怎么写的?
    我一直用 markdown 写了放 git 里,最近有人说不用 swagger 就落后了,我想,光文档里写一个返回数据如何使用都要写大半也,写到代码注释里,那还不半屏幕的注释啊。。。
    rockyou12
        75
    rockyou12  
       2019-06-05 17:11:03 +08:00
    @NoKey 如果只是字段多,嵌套复杂,像 spring-fox 这种是自动扫描类信息的,不需要手写。其它语言基本也有这种 swagger 的自动生成工具
    NoKey
        76
    NoKey  
       2019-06-05 17:15:29 +08:00
    @rockyou12 不是嵌套复杂,是业务复杂,服务器发出去的数据,需要指定的方式才能解析出来,这个指定的方式,需要写半夜文档的样子。。。还有,返回去的字段也是嵌套的,比如 json 里面嵌了一个 String,但是这个 String 实际是个 json,swagger 能解析道这个 String 的结构么?
    rockyou12
        77
    rockyou12  
       2019-06-05 17:24:23 +08:00
    @NoKey 你这种除了手写没有其它解决办法
    rockyou12
        78
    rockyou12  
       2019-06-05 17:27:26 +08:00
    @NoKey swagger 其实现在不只是一个文档工具,也是 open api 这个规范的实现,open api 基本只支持 rest api。你接口不符合 rest 那就没办法了ㄟ( ▔, ▔ )ㄏ
    BlBana
        79
    BlBana  
       2019-06-05 17:30:00 +08:00
    话说楼主得是渣康的 ...
    cwx391497
        80
    cwx391497  
       2019-06-05 17:35:26 +08:00
    我也是,我这文档都 400 多页了,大范围编辑真的想死
    我的想法是用 html 重写,或者把文档做成 chm 格式的,会比较好维护(积重难返.....🤣)
    poisedflw
        81
    poisedflw  
       2019-06-05 17:37:33 +08:00
    自己部署一套 eolinker
    dif
        82
    dif  
       2019-06-05 17:38:30 +08:00
    yapi
    NoKey
        83
    NoKey  
       2019-06-05 17:50:01 +08:00
    @rockyou12 谢谢
    thfurior
        84
    thfurior  
       2019-06-05 17:55:03 +08:00
    别问,问就 doc
    jaryur
        85
    jaryur  
       2019-06-05 18:13:38 +08:00 via Android
    @chendy 生成 javadoc 只是第一步,原生的 javadoc 很不便于查询和展示,我是生成了自定义格式的类 javadoc markdown 文件
    guiling
        86
    guiling  
       2019-06-05 18:46:34 +08:00 via Android
    yapi
    linvaux
        87
    linvaux  
       2019-06-05 19:05:00 +08:00 via Android
    eolinker
    chendy
        88
    chendy  
       2019-06-05 19:10:58 +08:00
    @jaryur 是开源的吗?想参考一下
    yoshiyuki
        89
    yoshiyuki  
       2019-06-05 19:19:42 +08:00
    showdoc
    Egfly
        90
    Egfly  
       2019-06-05 19:21:08 +08:00 via iPhone
    Yapi
    sunjiayao
        91
    sunjiayao  
       2019-06-05 19:26:38 +08:00
    apidoc +1 养成改代码前先改文档注释,再写个自动发布脚本。简直不要太舒服
    zhangtao
        92
    zhangtao  
       2019-06-05 19:43:42 +08:00
    yapi +1
    jaryur
        93
    jaryur  
       2019-06-05 20:27:00 +08:00 via Android
    @chendy 目前还在开发中,用的是 docsify 做展示
    blueorange
        94
    blueorange  
       2019-06-05 20:33:53 +08:00
    swagger-ui.html
    newmind
        95
    newmind  
       2019-06-05 20:35:04 +08:00
    代码即文档
    wc951
        96
    wc951  
       2019-06-05 20:35:25 +08:00 via Android
    spring restdoc,文档片段写在单元测试里
    jiangzhuo
        97
    jiangzhuo  
       2019-06-05 20:58:58 +08:00
    swagger
    lygmqkl
        98
    lygmqkl  
       2019-06-05 21:54:50 +08:00
    postman / showdoc

    api 文档而已 搞那么复杂干嘛? 难道你们编程的生活还不够苦难吗?
    kindle958
        99
    kindle958  
       2019-06-05 22:39:17 +08:00
    @acumen 你牛逼
    changwei
        100
    changwei  
       2019-06-05 22:42:57 +08:00
    @liuxey
    @TommyLemon
    @Macolor21
    @liuxey
    @via
    萌新弱弱地问一句,他的 api 文档项目有什么问题吗?开源免费为什么要喷啊 = =
    1  2  
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   1362 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 26ms · UTC 17:38 · PVG 01:38 · LAX 09:38 · JFK 12:38
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.