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

各位公司的 API 接口文档是用的什么方式?

  •  1
     
  •   aschoolboy · 2018-07-18 20:10:15 +08:00 · 22782 次点击
    这是一个创建于 2070 天前的主题,其中的信息可能已经有所发展或是发生改变。

    之前公司的 API 接口文档写在 word 里,放在 github 上。
    缺点很多,不能同时编辑,一同时编辑就冲突.
    我趁一期项目结束,搭了个开源 API 接口网站:eolinker。
    给师父看了,说可以,叫我把所有接口都牵进去了。准备让所有同事用了。
    结果有的同事一看感觉不方便,说可以用 markdown 来写。
    又安排我找个用 markdown 写的 api 文档模板

    所以想问问大家的 api 接口文档是采用什么方式的?

    117 条回复    2019-01-17 09:53:56 +08:00
    1  2  
    wangcansun
        1
    wangcansun  
       2018-07-18 20:15:21 +08:00   ❤️ 1
    swagger?=>代码生成文档。
    markdown 模式的=>Apiary ?
    cnbattle
        2
    cnbattle  
       2018-07-18 20:24:01 +08:00
    公司用的 apizza
    cnbattle
        3
    cnbattle  
       2018-07-18 20:25:16 +08:00
    可以用 http://www.xiaoyaoji.cn/ 支持 md
    DiverRD
        4
    DiverRD  
       2018-07-18 20:48:49 +08:00 via iPhone   ❤️ 1
    我推荐 Yapi 楼主可以搜搜看
    billlee
        5
    billlee  
       2018-07-18 21:24:12 +08:00   ❤️ 4
    口述
    aschoolboy
        6
    aschoolboy  
    OP
       2018-07-18 21:30:21 +08:00
    @billlee #5 哈哈 可以
    mhtt
        7
    mhtt  
       2018-07-18 21:35:51 +08:00
    我要回农村
    yidinghe
        8
    yidinghe  
       2018-07-18 22:01:38 +08:00 via Android   ❤️ 1
    写了一个框架,要求必须用注解语法来定义接口,然后提供一个 web 页面供查看注解内容。所以文档和代码是同步的。
    PHPJit
        9
    PHPJit  
       2018-07-18 22:02:36 +08:00 via Android
    eolinker
    aschoolboy
        10
    aschoolboy  
    OP
       2018-07-18 22:10:24 +08:00
    @mhtt #7 咋啦兄弟
    RangerWolf
        11
    RangerWolf  
       2018-07-18 22:45:48 +08:00
    虽然楼主你搭建的 eolinker 确实强大, 但是我组就用的 markdown

    感觉足够了。。。
    因为在打开 git 项目的时候, 顺手就能看到 哦, 这个项目的 Readme 有大概介绍。 形成自然反馈了。


    可能 API 比较多比较复杂的场景适合 eolinker ?
    dengtongcai
        12
    dengtongcai  
       2018-07-18 22:58:50 +08:00 via Android
    postman 临时文档……
    oneisall
        13
    oneisall  
       2018-07-18 23:00:52 +08:00
    graphql = =
    TommyLemon
        14
    TommyLemon  
       2018-07-18 23:05:07 +08:00
    自动生成的
    apijson.org/

    后端接口和文档自动化,前端(客户端) 定制返回 JSON 的数据和结构!
    github.com/TommyLemon/APIJSON
    TommyLemon
        15
    TommyLemon  
       2018-07-18 23:05:32 +08:00
    @TommyLemon 不需要写任何代码哦
    xiaojie668329
        16
    xiaojie668329  
       2018-07-18 23:09:34 +08:00 via iPhone
    @billlee 之前我对接的后端真的是过来跟我口述的,或者在微信发条消息……有一次直接把代码截图给我。我搭了个 swagger 又不想学写文件,只好让建个 md 让他更新在上面。🤣
    TommyLemon
        17
    TommyLemon  
       2018-07-18 23:09:39 +08:00
    格式是这样的,发不了图片凑活看吧,右侧往下翻,在自动生成的代码下方。

    2. User
    说明:
    用户公开信息表。
    对安全要求高,不想泄漏真实名称。对外名称为 User

    字段:
    名称 | 类型 | 最大长度| 详细说明
    id | Long | 15 | 唯一标识
    sex | Integer | 2 | 性别:0-男 1-女
    name | String | 20 | 名称
    tag | String | 45 | 标签
    head | String | 300 | 头像 url
    contactIdList | List | 不限 | 联系人 id 列表
    pictureList | List | 不限 | 照片列表
    date | Timestamp | 不限 | 创建日期
    WEAlex
        18
    WEAlex  
       2018-07-18 23:09:47 +08:00 via Android
    没有用 rap2 的么,虽然有一些 bug
    TommyLemon
        19
    TommyLemon  
       2018-07-18 23:10:26 +08:00
    @TommyLemon
    创作不易,GitHub 右上角点 Star 支持下吧,谢谢^_^
    github.com/TommyLemon/APIJSON
    TommyLemon
        20
    TommyLemon  
       2018-07-18 23:14:37 +08:00
    @TommyLemon APIJSONAuto 在线工具还有很多其它功能:
    自动生成文档,清晰可读永远最新
    自动生成请求代码,支持 Android 和 iOS
    自动生成 JavaBean 文件,一键下载
    自动管理与测试接口用例,一键共享
    自动校验与格式化 JSON,支持高亮和收展

    创作不易,GitHub 右上角点 Star 支持下吧,谢谢^_^
    github.com/TommyLemon/APIJSON
    ioc
        21
    ioc  
       2018-07-18 23:16:31 +08:00 via Android
    @TommyLemon 我就说一句,你这个除了 mysql,其他数据库都不支持
    opengps
        22
    opengps  
       2018-07-18 23:28:23 +08:00 via Android
    注释自动生成的 webapi 说明文档
    keenwon
        23
    keenwon  
       2018-07-19 00:01:45 +08:00
    chenry
        24
    chenry  
       2018-07-19 00:52:59 +08:00
    什麼方式?不存在的。。。
    問 Dev 是 Get 還是 POST ?你都試一下
    問參數是什麼格式的?你看一下代碼

    運維天天和我吐槽~~
    ivanchou
        25
    ivanchou  
       2018-07-19 02:27:18 +08:00 via Android
    拿阿里的 Rap 改良的
    loveCoding
        26
    loveCoding  
       2018-07-19 06:20:57 +08:00
    走 rpc ,传输用的 pb 协议 ,感觉还不错
    Ethanp
        27
    Ethanp  
       2018-07-19 06:23:46 +08:00 via Android
    showdoc
    xiaqi
        28
    xiaqi  
       2018-07-19 06:34:55 +08:00 via Android
    showdoc
    lrh3321
        29
    lrh3321  
       2018-07-19 07:23:48 +08:00 via Android
    postman 或者手写 openapi 3.0 格式的文档,然后放到 swagger ui 上看。文档和手动测试一体化,就是后端累死了
    BaiMax
        30
    BaiMax  
       2018-07-19 08:23:28 +08:00 via Android   ❤️ 1
    在用 showdoc,有一键模板
    justfindu
        31
    justfindu  
       2018-07-19 08:27:26 +08:00
    word 方式可以试试 QQ 的文档共享编辑那个. 真的还挺棒的
    947211232
        32
    947211232  
       2018-07-19 08:54:03 +08:00
    搭建内网 github,使用 gitbook 建档
    smilenceX
        33
    smilenceX  
       2018-07-19 08:55:02 +08:00
    听说过德鲁依没?
    CFO
        34
    CFO  
       2018-07-19 08:57:53 +08:00 via Android   ❤️ 2
    swagger 改代码时顺手就把文档维护了 本身支持在线文档 也可以用其他工具导出 html pdf
    cyokvip
        35
    cyokvip  
       2018-07-19 08:58:06 +08:00
    apizza,不过文件夹下不能建立子文件夹
    v2chou
        36
    v2chou  
       2018-07-19 09:02:35 +08:00
    口口相传 心累 我是前端
    ofooo
        37
    ofooo  
       2018-07-19 09:04:52 +08:00 via iPhone
    我最近尝试用蚂蚁金服出的语鹊,楼主去看看怎么样吧,不涉及机密的话感觉还不错
    LeungJZ
        38
    LeungJZ  
       2018-07-19 09:06:01 +08:00
    口口相传+1.
    Flicker
        39
    Flicker  
       2018-07-19 09:11:42 +08:00 via Android
    就直接用 markdown 写的,文档这个东西只要有一定规范,大家都能看懂就行了。
    cqu1980
        40
    cqu1980  
       2018-07-19 09:12:48 +08:00
    apidoc~~~~~~~~~~~~~~~~
    joeke
        41
    joeke  
       2018-07-19 09:14:03 +08:00
    showdoc apizz 都比较好用
    jasonslyvia
        42
    jasonslyvia  
       2018-07-19 09:18:40 +08:00   ❤️ 1
    swagger + pont + ts,如丝般顺滑
    jianlu
        43
    jianlu  
       2018-07-19 09:22:38 +08:00
    showdoc + 1
    adrianXu
        44
    adrianXu  
       2018-07-19 09:35:32 +08:00
    swagger2
    guoyuchuan
        45
    guoyuchuan  
       2018-07-19 09:38:45 +08:00
    swagger
    TommyLemon
        46
    TommyLemon  
       2018-07-19 09:53:03 +08:00
    @adrianXu 你是怎么发出图片的?
    adrianXu
        47
    adrianXu  
       2018-07-19 09:55:10 +08:00
    @TommyLemon #46 截图 command+v
    CabalPHP
        48
    CabalPHP  
       2018-07-19 09:56:12 +08:00
    jinhan13789991
        49
    jinhan13789991  
       2018-07-19 09:57:14 +08:00
    后台口头传述,绝对不会泄露
    specita
        50
    specita  
       2018-07-19 10:02:01 +08:00
    在用 Apiary,不过语法要了解下不怎么方便,学习成本有点高, 正准备换
    IMuMa3
        51
    IMuMa3  
       2018-07-19 10:03:17 +08:00
    eoLinker +1
    lydbilibili
        52
    lydbilibili  
       2018-07-19 10:06:18 +08:00
    没有文档
    Heanes
        53
    Heanes  
       2018-07-19 10:09:06 +08:00
    swagger 或者 rap
    tt67wq
        54
    tt67wq  
       2018-07-19 10:40:59 +08:00
    我司一般靠睿智的程序员去源码里面考古
    Smilencer
        55
    Smilencer  
       2018-07-19 10:43:43 +08:00
    之前用 swagger,现在我再推广使用 postman collection, 作为后端必须产出文档之一。前端和测试 MM 都夸我好贴心,后端兄弟对我恨子入骨。。。
    A555
        56
    A555  
       2018-07-19 10:47:24 +08:00
    给个地址 给个例子 自己玩
    TommyLemon
        57
    TommyLemon  
       2018-07-19 10:55:55 +08:00
    https://oscimg.oschina.net/oscnet/f123d05a95009216791d54831d266448cac.jpg

    自动生成文档,清晰可读永远最新
    自动生成请求代码,支持 Android 和 iOS
    自动生成 JavaBean 文件,一键下载
    自动管理与测试接口用例,一键共享
    自动校验与格式化 JSON,支持高亮和收展

    有视频教程哦
    apijson.org

    GitHub 右上角点 Star 支持下吧,谢谢^_^
    github.com/TommyLemon/APIJSON
    TommyLemon
        58
    TommyLemon  
       2018-07-19 10:56:44 +08:00
    TommyLemon
        59
    TommyLemon  
       2018-07-19 10:58:27 +08:00
    @Smilencer Swagger,APIDoc 等都要后端写大量注解代码啊,能不恨你么哈哈?
    用 APIJSONAuto 好了,全自动生成,一行代码都不用写
    linxl
        60
    linxl  
       2018-07-19 11:00:21 +08:00
    粘贴一段 json, 附上 url, method. 哈哈哈
    matthevv
        61
    matthevv  
       2018-07-19 11:00:45 +08:00 via iPhone
    Apidoc🤭
    hellopy
        62
    hellopy  
       2018-07-19 11:01:40 +08:00
    我司:svn+word+excel,wiki
    fuckgfwfuckgfw
        63
    fuckgfwfuckgfw  
       2018-07-19 11:03:30 +08:00 via Android
    zclHIT
        64
    zclHIT  
       2018-07-19 11:06:31 +08:00 via iPhone
    IDP-Lite..
    yzmm
        65
    yzmm  
       2018-07-19 11:09:02 +08:00
    swagger+markdown
    shd
        66
    shd  
       2018-07-19 11:13:32 +08:00
    apidoc +1
    skyline45
        67
    skyline45  
       2018-07-19 11:19:09 +08:00
    word 啊 2333333333
    zavieryip
        68
    zavieryip  
       2018-07-19 11:23:37 +08:00
    showdoc+1
    whypool
        69
    whypool  
       2018-07-19 11:28:03 +08:00
    excel
    Lawlieti
        70
    Lawlieti  
       2018-07-19 11:30:12 +08:00
    口述
    x537196
        71
    x537196  
       2018-07-19 11:33:16 +08:00
    魔改 showdoc
    cai314494687
        72
    cai314494687  
       2018-07-19 11:38:47 +08:00
    自己搭建 eolinker
    Light3
        73
    Light3  
       2018-07-19 11:43:41 +08:00
    https://apiview.com/
    这个 人少完全 ok
    hasbug
        74
    hasbug  
       2018-07-19 11:50:34 +08:00
    以前 swagger,现在公司 word···好烦人
    pandaaa
        75
    pandaaa  
       2018-07-19 11:53:00 +08:00 via Android
    用的 wiki
    TommyLemon
        77
    TommyLemon  
       2018-07-19 12:19:04 +08:00
    V2EX 评论里发个图片这么麻烦。。。
    Edwards
        78
    Edwards  
       2018-07-19 12:34:40 +08:00
    @billlee
    NicholasYX
        79
    NicholasYX  
       2018-07-19 12:52:44 +08:00
    写个页面,罗列按钮,怎么调用直接写按钮点击事件里面,拿去自己点着玩,右键查看源代码 手动滑稽.
    xrr2016
        80
    xrr2016  
       2018-07-19 13:01:57 +08:00
    之前公司用什么 txt 文件,或者 md,在我的推荐下用了 YApi,很好用的;
    pandasoda
        81
    pandasoda  
       2018-07-19 13:04:45 +08:00
    @billlee
    sakishum
        82
    sakishum  
       2018-07-19 13:11:36 +08:00
    口传心授
    iFlicker
        83
    iFlicker  
       2018-07-19 13:24:55 +08:00
    @billlee 对的, 反正人家也不看 都是过来问
    Heimo
        84
    Heimo  
       2018-07-19 13:45:14 +08:00
    用过 swagger,showdoc,最终使用 apizza
    jianpanxia
        85
    jianpanxia  
       2018-07-19 13:47:08 +08:00
    自己看代码去..
    bufpay
        86
    bufpay  
       2018-07-19 13:48:07 +08:00
    (bufpay.com 个人收款 API)[https://bufpay.com/page.html] 直接是 html,用 github 的 wiki 也不错呀
    Jameson1559
        87
    Jameson1559  
       2018-07-19 14:08:32 +08:00
    。。。我们连口口相传都没有。。全靠慧根自己领悟。。。
    NSAtools
        88
    NSAtools  
       2018-07-19 14:09:45 +08:00
    口口相传,代码连注释也没
    NonClockworkChen
        89
    NonClockworkChen  
       2018-07-19 15:28:14 +08:00
    虽然是老生常谈,但是挺有用的帖子。。。
    fml87
        90
    fml87  
       2018-07-19 15:35:15 +08:00
    项目立项的时候有详细的设计文档,项目一期用 swagger,二期、三期、四期接口变动超过 90%,人员也换了一轮,API、消息结构、一些部署配置项就全靠口口相传和猜了
    TingHaiJamiE
        91
    TingHaiJamiE  
       2018-07-19 15:36:00 +08:00
    yapi
    randyzhao
        92
    randyzhao  
       2018-07-19 15:39:19 +08:00
    手写 MD。。。
    beny2mor
        93
    beny2mor  
       2018-07-19 15:42:12 +08:00
    rap2
    TommyLemon
        94
    TommyLemon  
       2018-07-19 15:43:07 +08:00
    @fml87 Swagger 这种需要后端写大量注解代码的,后期当然维护困难。
    用 APIJSONAuto 吧,一行代码都不用写就能自动生成文档
    右上角点 Star 支持下吧^_^
    github.com/TommyLemon/APIJSON

    <img src="https://oscimg.oschina.net/oscnet/f123d05a95009216791d54831d266448cac.jpg" />
    TommyLemon
        95
    TommyLemon  
       2018-07-19 15:47:06 +08:00
    @TommyLemon 效果展示(右侧滚动到自动生成的代码的下方):
    apijson。org
    reus
        96
    reus  
       2018-07-19 15:52:46 +08:00
    用函数签名做文档,反正前端看得懂,先写文档,然后把文档复制到代码里,改下一些参数类型,然后加上函数体,就实现了接口
    sutra
        97
    sutra  
       2018-07-19 15:55:24 +08:00
    enunciate.
    soulmine
        98
    soulmine  
       2018-07-19 16:00:24 +08:00
    没有文档
    feiyuanqiu
        99
    feiyuanqiu  
       2018-07-19 16:28:22 +08:00
    @TommyLemon 需要程序员写大量注解,就没有把 swagger 用对

    VikingX
        100
    VikingX  
       2018-07-19 16:29:43 +08:00 via Android
    rap
    1  2  
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   5827 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 35ms · UTC 06:24 · PVG 14:24 · LAX 23:24 · JFK 02:24
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.